Skip to content
→ All work

Case study 25 / 37

ArchitectFlow

Design a system's architecture, data model, API and UI as one versioned document, check it with deterministic rules, and generate an implementation prompt from the exact saved revision.

Status
Experimental
Period
2026
Domain
Web · AI
Language
Python
Last push
26 OCT 2026
License
MIT OR Apache-2.0
Source of claims
README.md, docs/ARCHITECTURE.md, docs/LIMITATIONS.md, CHANGELOG.md, apps/api/architectflow/routes/auth.py, apps/api/architectflow/main.py, .github/workflows/ci.yml; release-gate verification 2026-10
Zoomed ArchitectFlow canvas showing labelled service connections

01/The problem

Diagrams drift from what gets built, AI assistants silently rewrite designs, and the prompt handed to a coding agent is usually assembled from stale chat history.

02/The system

A Next.js and FastAPI app backed by PostgreSQL. Every change (manual edit, import, restore or AI proposal) passes one integrity gate and becomes an immutable revision. AI output arrives as a change set that is diffed and validated before anyone applies it, and each generated prompt records the revision it came from and is marked OUTDATED when the design moves on.

Request path (docs/ARCHITECTURE.md)8 components
  • Next.js UI to Next.js server
  • Next.js server to FastAPI
  • FastAPI to Change sets
  • Change sets to AI providers
  • Change sets to Integrity gate
  • FastAPI to Integrity gate
  • FastAPI to Validation rules
  • FastAPI to PostgreSQL

03/Implementation

  1. 01Twelve workspaces share one typed document: requirements, an architecture graph with 18 component types, database entities with foreign keys and indexes, API endpoints mapped to columns, and UI theme tokens and pages.
  2. 02An untrusted-input pre-check and an integrity gate reject definite defects (duplicate ids, dangling edges, foreign keys to missing columns, NaN, NUL or over-deep JSON) with a 422 and a dotted field path. A failing document is never stored.
  3. 03Deterministic validation with 94 rule ids, keeping structural errors separate from recommendations that quote evidence and a fix.
  4. 04AI providers: a labelled offline example mode (the default), OpenAI-compatible Chat Completions and Anthropic Messages. Provider failures map to 502, 503, 504, 429 or 422 and never change the design.
  5. 05A prompt generator with 8 modes × 3 agent presets, and exports to Mermaid, PlantUML, C4, ERD, PostgreSQL DDL and OpenAPI 3.1.

04/Engineering

One document, not linked revisions

References from UI to endpoint to entity to data store are validated together. The trade-off is that every save writes the whole document, bounded by a 2 MB request limit.

AI output is a proposal

A change set is applied to a copy, run through the same integrity gate and shown as a diff with findings. Large destructive sets (at least 3 components and 40% removed) need explicit confirmation.

Session security

Argon2id passwords, HttpOnly, Secure, SameSite=Lax session cookies, a CSRF header on writes, rate-limited login, and a body limit enforced while reading, including chunked bodies without Content-Length.

05/Interface

The System architecture graph, zoomed in: API gateway, Auth service, Core API, Secrets manager, Sync service and Primary database with protocol-labelled edges.
The System architecture graph editor showing the 9 generated components and 10 typed connections, with Core API selected in the inspector.
Product vision workspace with the generated architecture shown as a pending, labelled example-mode change set before it is applied.
Validation findings for the saved revision: two form-field warnings and one accessibility recommendation, each with evidence, fix and location.
The UI/UX Design Studio theme editor: colour tokens, HEX/RGB/HSL editor and typography controls driving a live dashboard preview.
The page designer with the generated page tree, component palette, the Inventory items page canvas and its page settings and states.
The Backend & API implementation prompt generated from saved revision 6, with every line labelled CONFIRMED or ASSUMPTION.
The project overview on a phone, with the workspace switcher collapsed into a dropdown and component, requirement and entity counts.

Real screenshots of the running software. Captions state the data shown.

06/Tech stack

  • Next.js 16
  • React 19
  • React Flow
  • FastAPI
  • Python 3.12
  • SQLAlchemy
  • PostgreSQL
  • Alembic
  • Vitest
  • Playwright
  • Docker

07/Result

Verified outcomes

  • Release-gate verification (2026-10): 172 API tests on PostgreSQL, 48 Vitest tests and 20 Playwright end-to-end specs passed; Alembic upgrade → downgrade → upgrade verified.
  • Docker images and a Compose file; the live AI path was verified against a local OpenAI-compatible model.

Known limitations

  • Single-owner projects: read-only share links, but no editor roles or real-time co-editing.
  • Rate limits are in memory per API process; the canvas is built for screens of 1024 px and wider.
  • Real model output quality is not evaluated; diagrams are export-only.

08/Links

GitHub repository ↗

Related work

Next case study

SLM →