ArchDocs
Start free

 Workflow

The system of record for software engineering.

Design it. Build it. Verify it.

Keep design docs, architecture, decisions and what each work session found in one record. Engineers and coding agents work from the same plan, pick up what earlier sessions learned, and review what the evidence supports.

Start freeTry the demo

Free includes architecture docs, MCP access and ten design docs within Free plan limits. Unlimited design docs start on Team.

Fictional example · recreated ArchDocs views

The next session can pick up what the last one found

Ten services are moving off an old API field. Claude Code finds a nightly worker the plan missed: remove the field and its invoice export breaks. ArchDocs keeps that finding with the plan, so the next engineer or agent gets it when they ask for context.

One finding, two sessions

Session 1

Claude Code · run by Priya Raman

01Found

invoice-worker still reads customer_name. Removing the field would break its nightly invoice export.

ArchDocs Work Log · DD-0031

E-7DeviationAgent-reported

Next: Keep customer_name until invoice-worker reads customer. Add a contract test.

E-7Same record
Session 2

Codex · run by Sam Okafor

02Retrieved

Codex asks ArchDocs for the migration context with get_task_context.

Returned context · DD-0031

Keep customer_name in the response until invoice-worker reads customer.

Constraint · from E-7 · Proposed by an agent

03Acted

Kept customer_name and added the missing invoice-worker contract test in #215.

Agent-reportedReview evidence in Verify it
View context details
E-7DeviationAgent-reported

Claude Code run by Priya Raman

Found
invoice-worker reads customer_name in jobs/export_invoices.py. It is not in the plan.
Consequence
Step 3 would break the nightly invoice export.
Next
Keep customer_name until invoice-worker reads customer. Add a contract test for invoice-worker.

Captured as a constraint

E-7

Keep customer_name in the response until invoice-worker reads customer.

Proposed by an agentFrom E-7
Q2

Who moves invoice-worker to customer?

Open

Prompt

Continue DD-0031: move Orders to customer, then remove customer_name.

Requests context over MCP

get_task_context
  task: "Move Orders to customer and remove customer_name"
  repo: { fullName: "example/accounts-api", paths: ["src/accounts/"] }
  designDocId: "8c1e…"  (DD-0031)

Returned (excerpt)

Decisions and constraints

  • E-7

    Keep customer_name in the response until invoice-worker reads customer.

    DD-0031 CONSTRAINT · captured from E-7 on DD-0031 (Work Log)

    Proposed

Current

  • DD-0031 · Replace customer_name in the Accounts API response

    CurrentApproved by a person

Open questions

  • Q2

    Q2 · Who moves invoice-worker to customer?

    Open

Acceptance criteria

  • AC-3 · invoice-worker exports invoices without customer_name

    Pending

  • AC-4 · All ten original consumers have migration evidence

    Pending

Next action

Moves Orders to customer in #214. Leaves customer_name in place because of the E-7 constraint, and adds the missing invoice-worker contract test in #215. Records both as E-9.

Agent-reported

Context is requested, not injected. The ArchDocs MCP server asks agents to request it before they plan a change, and people open the same records on the Context page. A proposed constraint is a record for the next session to weigh, not an enforced rule, so Verify it checks what the work actually did.

Work logs come with design docs on every plan. Task context is on Team, Business and Enterprise. GitHub pull requests and checks are on Business and Enterprise.

· One migration through plan, build and verification.

 Design it

Map the system your team actually runs

Draw services, queues, databases and APIs once, then reuse them on every diagram. Archdocs shows what depends on each one, from the docs your team keeps.

  • Endpoint cards, data models, sequence diagrams and cloud blocks on one canvas.
  • One object per service, so a rename or new owner updates every diagram that uses it.
  • Every diagram is YAML you can review in Git, with a pull request check that flags docs that may be stale.

Plan · Architecture docs, shared objects and the MCP server are on every plan.

Object
Bookings DB
Kind
Datastore
Engine
PostgreSQL 16
Change

Dispatch Service doc

Dispatch ServiceService
Bookings DBPostgreSQL 16

Booking Lifecycle doc

Booking ServiceService
Bookings DBPostgreSQL 16

Refunds Service doc

Refunds ServiceService
Bookings DBPostgreSQL 16

Bookings DB is PostgreSQL 16 in all three docs.

Changing Bookings DB affects 9 objects across 7 docs.Example

· Change it once. Every diagram that uses it follows.
See how architecture works

 Design it

Decide before you build, and keep the reasons

A design doc holds the spec, the open questions and the decision, next to the services it changes. Decision records keep the options you rejected and why.

  • Open questions stay open until a person answers them.
  • Decision records show the considered options and what superseded them.
  • Named reviewers approve the spec, and later edits are recorded as amendments.
  • An AI reviewer checks the spec against your other docs and code before people review it, and you can post its findings as comments.

Plan · Ten design docs on Free; unlimited design docs on Team and above. Review and approvals on Business and Enterprise. AI review on Team and above.

Product screenshots from the DD-0031 example, the same fictional migration as the demo above. Open the example

See how design docs work

 Build it

Give people and coding agents the same plan

The implementation plan lists the changes and tasks. Engineers work from it in Archdocs, and coding agents read the same spec, plan and open questions over MCP.

  • Agents get the open questions with the plan, and Archdocs tells them to ask rather than decide.
  • Evidence an agent submits is labeled as the agent's report until a person reviews it.
  • Agents ask for a task's context before they start, and leave a handoff when they stop.
  • Send plan tasks to Linear when your team tracks work there. Linear is on Business and Enterprise, in early access.
Works with Claude, Cursor, Codex and VS Code

Plan · The MCP server is on every plan. Ten design docs on Free; unlimited design docs on Team and above.

Product screenshots from the DD-0031 example, the same fictional migration as the demo above. Open the example

See how agents use Archdocs

 Verify it

Review what landed against the plan

Compare the planned changes with the changes your team and agents recorded, next to pull requests and checks from GitHub.

  • Gaps show both ways: planned work with no recorded change, and changes nobody planned.
  • Pull request and check results come from GitHub.
  • Acceptance criteria say what has to be true, and each piece of evidence shows where it came from.

Plan · Plan versus actual on every plan. GitHub evidence on Business and Enterprise. Acceptance criteria on every plan, up to 10 per design doc on Free.

Product screenshots from the DD-0031 example, the same fictional migration as the demo above. Open the example

See how verification works

 Build it

Pick up where the last session stopped

Each design doc keeps a work log of what was done, what's blocked and what comes next, with every entry marked as reported by a person or an agent. When someone picks the task up, they ask for its context and get the decisions, open questions and history linked to that work.

  • Handoffs list what's done, what's blocked and what's next, with a resume prompt for the next session.
  • Commits cited in an entry are checked against GitHub when Archdocs can read the repository.
  • Task context labels every record with who approved it and how it was found.
  • Agents ask for it over MCP; people use the Context page. Records you can't open are left out.

Plan · Work logs come with design docs on every plan. Task context is on Team, Business and Enterprise.

Worked example above: E-7 is recorded in session one, returned by get_task_context in session two, and checked as AC-3 in Verify it.

Follow the finding
See context and handoffs

 Templates

Start from a working example

Architecture decision record exampleA fictional architecture decision record in MADR fields, with context, considered options, decision and consequences for choosing carrier REST APIs over EDI.Read the example →
Shipper REST endpointsDocument quote and booking requests, webhook subscriptions and load status responses.Open in editor →
AWS deployment architecturePlace an API cluster and PostgreSQL databases inside account, VPC and subnet boundaries.Open in editor →
C4 system contextMap an outreach platform, the person who uses it and its email provider.Open in editor →
Software design document example and template: spec, plan and evidenceA blank software design document template you can copy or download, plus a completed fictional example with its spec, implementation plan, work log and evidence.Read the example →
Booking data modelTrace foreign keys between freight shipments, quotes, bookings and loads.Open in editor →
Coding agent handoff example from a work logA fictional work log where Claude Code finds a worker the plan missed and leaves a handoff, then Codex and the team pick the work up from it.Read the example →
API migration plan exampleA fictional API migration plan mid-flight. Ten consumers move off an old response field one pull request at a time, with acceptance criteria checked by GitHub and PostHog.Read the example →
Book a load sequenceFollow a quote request through booking confirmation and asynchronous dispatch.Open in editor →

 Founder note

Why I built ArchDocs

I built ArchDocs so a service is defined once and used in every document that needs it. Design docs, decisions and recorded changes now build on those same objects.

Aylon, founder of ArchDocs

Read my note

 FAQ

Frequently asked questions

Is it free?

Yes. Free covers up to three people, ten architecture docs, shared objects, the MCP server and ten design docs. Team adds unlimited design docs and task context. Business adds reviews, approvals and GitHub evidence.

See pricing and plan limits
We write design docs in markdown already. Why change?

Markdown works well for many teams. Archdocs becomes useful when decisions, open questions, architecture references, and implementation records need to stay connected across people and changes. You can import a markdown plan as is.

Isn't this one more thing to maintain?

Shared objects reduce duplicate edits. People and agents can contribute records, and supported integrations add signals about work and documentation that may need review. Your team still decides what is correct.

Do we keep GitHub and Linear?

Yes. Code stays in GitHub and work tracking stays in Linear. Archdocs links pull requests, checks and issues to the design doc they belong to, so the engineering record points at those tools instead of replacing them. GitHub is on Team and above; Linear is on Business and Enterprise, in early access.

How small can we start?

With one proposal. Write it as a design doc, mention the services it changes, and record the work as it lands. Free includes ten design docs and ten architecture docs.

Read the MCP setup guide
Why not build this ourselves?

You could keep a folder of docs and a script or two. The work that lasts is maintaining permissions, history, authority labels, attribution, connectors and evidence over time, for people and agents at once. That is what Archdocs maintains for you.

Can we take our data with us?

Diagrams export as SVG, PNG or PDF, and every diagram is YAML you can copy. A design doc exports as markdown, whole or one variation at a time, including work log entries. The audit log exports as CSV or JSON. Approvals, acceptance criteria results and decision records are not included in those exports today.

Does it work with my AI tools?

Yes, if your client supports remote MCP servers with OAuth. Connect to https://mcp.archdocs.io/mcp and sign in through your browser. The agent can read and update architecture docs, write design docs and decisions, record changes, add work log entries and ask for a task's context (task context is on Team and above).

How does the next person or agent pick up the work?

From the design doc's work log. The latest handoff says what's done, what's blocked and what's next, and task context gathers the approved decisions, open questions and history linked to the work. Agents get the same over MCP. Work logs come with design docs on every plan. Task context is on Team, Business and Enterprise.

Where is my data stored?

Architecture documents are stored in PostgreSQL in the United States. The API and database run on Northflank, the web apps run on Vercel, and uploaded files are stored in Cloudflare R2.

 Start

Start with one engineering change.

Explore the architecture editor for free, or see how Design Docs connect a proposal, its decisions, and the record of the work.

Try the architecture editorExplore Design Docs