Release Evidence Autopilot
Build Blueprint

# AI Build Blueprint

Release Evidence Autopilot — a focused B2B SaaS that turns scattered software-release records into one reviewable proof packet.

## Application

Build a web application for small software teams that must explain what changed in a release, which checks passed, who approved it, and where it was deployed. The application connects to one source repository, imports evidence for a completed deployment, identifies missing information, and publishes a source-linked release packet.

The MVP is a release-evidence workspace. It is not a deployment tool, general engineering analytics suite, service catalog, or compliance-certification product.

## Users

The primary user is an engineering manager, release manager, platform lead, or technical project manager at a 15–100 person software organization. They need to assemble a trustworthy release record without opening several tools and copying screenshots into a spreadsheet or document.

The secondary user is a security, operations, customer-success, leadership, or compliance reviewer. They need to verify a release without repository-administrator knowledge.

Users must be able to connect a repository safely, select a completed deployment, see which evidence is present or missing, add explanations without changing imported facts, and publish an immutable packet.

## Core Product

Transform records that already exist in a repository and deployment workflow into one traceable release packet. Every imported claim retains its source link and retrieval time. User-entered explanations remain visibly separate from imported facts.

The proof outcome is simple: a release owner can produce a complete packet in under ten minutes, and a reviewer can understand it without reconstructing the release manually.

## Core Features

- Email-link sign-in and one organization workspace.
- Read-only GitHub connection with up to five repositories.
- Completed-deployment picker.
- Import of deployment, commit, pull request, workflow, check, environment, and approval metadata.
- Deterministic completeness checklist with present, missing, and not-applicable states.
- Editable release summary, customer-impact note, risk note, rollback note, and ticket links.
- Source links and retrieval timestamps for every imported evidence item.
- Immutable, versioned packet publishing.
- Read-only packet view and PDF export.
- Audit events for connection, import, edit, publish, revoke, export, and deletion.

Core functionality must work end to end. Do not substitute mock imports, fake completeness results, or buttons that do not perform their stated action.

## Secondary Features

- Up to three organization members with owner, editor, and reviewer roles.
- Privacy-safe analytics for setup, import, publish, source-open, and export events.
- Connection revocation and organization deletion.
- Retryable background jobs when imports or PDF generation exceed request limits.
- Clear empty, loading, failure, rate-limit, and permission states.

Defer custom compliance frameworks, enterprise SSO, SCIM, multi-provider support, automated release execution, custom dashboards, and data-residency controls.

## Primary Workflow

1. The user signs in with an email link and creates an organization.
2. The user selects **Connect GitHub** and approves a read-only GitHub App installation.
3. The system stores the provider credential securely on the server and lists accessible repositories.
4. The user selects one repository and one completed deployment.
5. The system imports related commits, pull requests, workflow runs, checks, environment records, and approvals.
6. The system evaluates the evidence and opens a draft packet with missing items highlighted.
7. The user reviews facts, adds explanations, and marks unsupported items not applicable with a reason.
8. The system reruns completeness checks and blocks publication while required evidence is missing.
9. The user publishes the packet.
10. The system creates an immutable version, calculates a content hash, records an audit event, and exposes a read-only view plus PDF export.

## Pages and Screens

### Sign In

Display the product promise, email field, submit action, privacy note, and return-to context. Support default, submitting, email-sent, expired-link, invalid-link, and service-error states. A successful sign-in returns the user to the requested route.

### Organization Setup

Display organization name, connection status, **Connect GitHub**, and setup progress. After authorization, show accessible repositories. Provider denial explains that no repository data was stored and offers a safe retry.

### Deployment Picker

Display the repository, completed deployments, environment, status, commit, and deployment time. Support loading, pagination, no-results, rate-limit, and retry states. Selecting a deployment starts one idempotent import job.

### Draft Packet

Display release identity, imported facts, source links, completeness status, missing items, editable explanations, save state, and publish action. Facts and commentary use different visual treatments. Publication stays disabled until blocking checks pass.

### Published Packet

Display packet version, content hash, summary, evidence, source links, approvals, checks, deployment outcome, risk and rollback notes, publication time, and PDF export. A revoked or deleted packet shows an explicit state.

### Settings

Display members, roles, repository connection, data-retention summary, revoke action, and deletion action. Destructive actions require confirmation and state their consequences.

Desktop is the primary authoring layout. Tablet and mobile support review, source opening, publication, and export without horizontal overflow.

## Data

- **User**: id, email, createdAt, lastSignInAt.
- **Organization**: id, ownerUserId, name, createdAt, deletedAt.
- **Membership**: organizationId, userId, role, createdAt.
- **ProviderConnection**: id, organizationId, provider, encryptedToken, scopes, status, installedAccountId, createdAt, revokedAt.
- **Repository**: id, organizationId, connectionId, providerRepositoryId, owner, name, defaultBranch, active.
- **Release**: id, organizationId, repositoryId, providerDeploymentId, environment, commitSha, status, deployedAt, importedAt.
- **EvidenceItem**: id, organizationId, releaseId, evidenceType, providerRecordId, sourceUrl, sourcePayload, observedAt, classification.
- **DraftPacket**: id, organizationId, releaseId, summary, customerImpact, riskNote, rollbackNote, ticketLinks, completenessState, version, updatedBy, updatedAt.
- **PacketSnapshot**: id, organizationId, draftPacketId, version, contentHash, renderedPayload, publishedBy, publishedAt, revokedAt.
- **AuditEvent**: id, organizationId, actorUserId, action, targetType, targetId, metadata, createdAt.

Every record is tenant-scoped. A release belongs to one repository; evidence belongs to one release; a draft packet has many immutable snapshots.

## Authentication

Use managed email-link authentication. Owners manage members, connections, retention, and deletion. Editors import releases, edit drafts, and publish packets. Reviewers read packets, open sources, and export PDFs.

Enforce authorization on the server for every organization resource. Validate signed provider state, encrypt credentials at rest, redact secrets from logs, and never return provider tokens to the browser. Row-level policies deny cross-organization access.

## Integrations

- GitHub App for repository and deployment metadata. Request read-only permissions only.
- Transactional email provider for sign-in links and essential account messages.
- PDF renderer that preserves the web packet's content and source links.
- Privacy-conscious analytics without private repository names or evidence bodies.
- Optional job service if import or PDF work exceeds request limits.

Treat every provider as replaceable. Confirm permissions, rate limits, retention terms, and failure behavior before implementation.

## Design Direction

Use a calm, evidence-led interface that feels trustworthy to technical and nontechnical reviewers. Favor readable typography, restrained color, clear status labels, generous spacing, and obvious source links. Use green only for confirmed completion, amber for attention, and red for blocking or destructive states. Never communicate state through color alone.

Imported facts and user explanations must be visually distinct. Every async action needs a visible loading state and a durable completion or failure message. Meet WCAG 2.2 AA contrast and keyboard requirements. Keep focus visible, label every form control, and announce job status changes.

## Technology

Recommended reference stack: TypeScript, a server-rendered React framework, managed PostgreSQL, managed email authentication, server-side API routes, object storage for PDFs, and a GitHub App. This supports a small team, relational evidence, server-side authorization, and a fast MVP release.

Database, hosting, authentication, repository provider, email provider, PDF renderer, analytics provider, and job runner are replaceable recommendations. Confirm or replace each choice based on the chosen builder, budget, and deployment target. Define environment variable names without values: DATABASE_URL, AUTH_SECRET, EMAIL_API_KEY, GITHUB_APP_ID, GITHUB_PRIVATE_KEY, GITHUB_WEBHOOK_SECRET, PDF_STORAGE_BUCKET, and ANALYTICS_WRITE_KEY.

## MVP Boundaries

Include one organization, three members, one GitHub connection, five repositories, completed-deployment import, completeness checks, editable explanations, immutable versions, packet viewing, PDF export, audit events, revocation, and deletion.

Do not include deployment execution, repository-setting changes, formal compliance certification, additional source-control providers, custom enterprise controls, SSO, SCIM, advanced dashboards, incident management, service catalogs, or automated ticket updates.

Stop or change direction if fewer than three of five design partners can create a packet, median preparation time is not reduced by at least half, or reviewers still reconstruct the release in source tools.

## Build Instructions

Functional requirements:

- FR-01: Require authentication before connection or packet access.
- FR-02: Retain provider IDs, source URLs, and retrieval timestamps for imported facts.
- FR-03: Keep user statements structurally separate from imported facts.
- FR-04: Run completeness rules on the server from stored records.
- FR-05: Prevent a failed import from creating a publishable packet.
- FR-06: Make import requests idempotent.
- FR-07: Make published snapshots immutable; edits create a new version.
- FR-08: Revoke provider credentials immediately when requested.
- FR-09: Return stable errors with code, message, retryable, requestId, and fieldErrors.

Acceptance criteria:

- AC-01: A permitted user can connect a test repository and import a completed deployment.
- AC-02: Imported records link to their sources.
- AC-03: Missing required evidence is never treated as present.
- AC-04: Repeating an import with the same key creates no duplicates.
- AC-05: A user from another organization receives no packet data.
- AC-06: Publishing creates a versioned immutable snapshot and content hash.
- AC-07: Revocation prevents another import.
- AC-08: The PDF contains the same substantive content and source links as the web packet.
- AC-09: A keyboard-only user can complete the primary workflow.

Build in vertical slices: authentication and tenancy; provider connection; one deployment import; completeness engine; draft packet; immutable publication; PDF export; then audit, revocation, deletion, and analytics. After each slice, run its unit, integration, permission, accessibility, and failure-path tests. Use staging and production with separate provider applications and databases. Require automated tests and a production build before deployment. Roll back application code to the prior revision while keeping migrations forward compatible.

Definition of done: all acceptance criteria pass; no cross-organization access is possible; secrets are absent from browser payloads, logs, and source control; loading, empty, error, retry, and rate-limit states work; the production build succeeds; the deployed revision is recorded; and a smoke test completes the primary workflow.

Build a functional MVP from this specification.

Start with the primary workflow and main application screen.

Do not create placeholder functionality for features identified as core requirements.

Ask for clarification only when a missing decision materially affects the product.