How Architectra works

In Sources, connect GitHub and choose a repository. Architectra previews the baseline, by default the head of the default branch, and pins that exact commit, even if the branch moves before you connect. You also choose the integration branch that later syncs and pull request checks follow.

Connecting captures the repository's file inventory and drafts a C4 architecture from the same commit. Selecting a baseline does not approve the code or verify any requirement.

A completed capture schedules Specification generation. AI reads the pinned files and proposes requirement candidates, chapter context and review notices. Each candidate cites the repository, commit, path, Git blob and lines it relies on.

• Candidates wait under Review › Extracted, grouped by the part of the system they were read from. Approving one adds it to the Specification as approved; dismissing drops it. Similar wording is flagged as a possible duplicate, and you decide whether to keep it separate, update the existing requirement or add it as evidence.
• Each statement is one sentence in EARS form: when, while, where or if a condition holds, a named system shall respond.
• Titles follow the workspace naming policy, checked by rules and a bounded AI check before you see the proposal.

Generated candidates are a starting point for review. Passing the structural citation checks does not show that a citation supports its claim, or that the Specification is complete.

The assigned system's owner or a designated reviewer decides each submitted requirement; workspace owners decide unassigned ones. Review is independent by default: nobody who wrote or edited the draft since its last approval can approve it. An extracted requirement nobody reworded takes one decision. Where the policy allows a self-review exception, the decision records it with its reason.

• Approval requires every cited file to be unchanged in the latest captured snapshot. An edited, moved or deleted citation blocks approval and names the file.
• Approved wording is immutable. Revisions sit beside the approved version, and History keeps every decision with the reviewer's role.

Approving a requirement turns each cited implementation and test definition into an active evidence binding: the reviewed link between the requirement and that code.

• Bindings are anchored to their syntax node with pinned grammars for TypeScript, JavaScript, Python and C/C++, or kept as exact text with the reason.
• Evidence linked later is proposed on its own and reviewed under the same rule, without reopening approved wording.
• Specification › Evidence lists every binding with its status, provenance and a GitHub link pinned to the commit and lines.

Assessment is opt-in. With the GitHub App installed and PR checks on, a workspace owner turns on Assess PRs against approved evidence for the repository. Each eligible pull request then gets one assessment per input version: a row for each approved requirement whose evidence the PR directly changes, and the coverage gaps it could not close. Changes lists them.

The system owner or a designated reviewer records an outcome for each row, with a rationale:

• No impactResolvedThe change does not affect the approved requirement. A reviewer may replace changed evidence with the PR's lines.
• Change neededOutstandingThe PR has to change before the requirement holds. The row stays outstanding on later assessments with the same evidence.
• Cannot determineUnresolvedThe evidence does not settle it. The row stays unresolved on later assessments with the same evidence.

• Under strict independence, a verified personal GitHub identity keeps a PR's author from resolving its rows.
• A decision carries to the PR's next assessment only while the reviewed evidence, scope and coverage stay equal. Incomplete coverage never carries a clean result.
• The GitHub check always concludes neutral. It reports rows and gaps; it never passes, fails or blocks a merge.

Every push to the tracked branch, Sync now and a daily run re-anchor approved evidence at the branch head. Evidence that is unchanged or moved follows the code. Evidence that changed, was deleted or became ambiguous is marked unresolved and shown in Sources and under Evidence for a person to review.

Replacement evidence a reviewer approved with No impact becomes active only after its pull request merges, and is discarded if the PR closes unmerged.

On a working or rejected draft, its author or a workspace owner can choose Refresh citations. Architectra re-anchors each citation at the repository's latest captured snapshot, the one approval compares with.

• Unchanged and relocated citations move to the snapshot.
• Changed, deleted, ambiguous and unsupported citations stay as they were and are listed with the reason, for the author to replace or remove. Nothing is dropped silently.
• A refresh is an edit: the refresher becomes a contributor for independence, and the title is validated again.

New revisions of an approved requirement start from the evidence its bindings maintain, so code that main only moved does not block the next approval.

Print / Save as PDF renders the working document or the approved requirements only. Download CSV exports the current approved revisions as two tables, which any workspace member can download:

• Requirements: reference, wording, owning system, the approving decision and its digests.
• Evidence: repository, commit, path, Git blob, lines, a pinned permalink and the binding's status.

Cells a spreadsheet would run as formulas are neutralized. The CSV shows approvals at download time; it is not a frozen release package.