Architecture Suite Overview

When developers give ambiguous prompts to AI coding assistants, agents routinely hallucinate folder structures, invent mismatched API contracts, and produce fragmented code. Archflow prevents architectural drift by generating an exact, cohesive 5-file specification suite before a single line of code is written.

Zero Route Drift

Client fetchers and backend endpoints share exact parameter keys, query names, and JSON status contracts.

Deterministic Prompts

Every task in the execution plan has a designated file path and automated verification command.

Agent-First Markdown

Formatted cleanly in GitHub markdown with ASCII trees and code fences for instant LLM parsing.

The 5 Core Specification Files

Every blueprint generated by Archflow consists of these five deterministic markdown documents:

projectOverview.md

Master Briefing & Setup

Executive summary, problem solved, target users, full tech stack justifications, port conventions, .env setup, and architectural principles.

Standard Document Sections

1. Executive Summary & Problem Solved
2. Target Users & Value Proposition
3. Tech Stack & Architectural Decisions
4. Repository Quickstart & Environment Setup
5. Core Engineering Principles

AI Agent Usage: Provides AI coding agents with high-level boundary context, repo conventions, and port rules so they do not invent incompatible libraries or clash ports.

requirements.md

Scope & Acceptance Criteria

Functional requirements, user personas, non-functional latency/auth constraints, and unambiguous acceptance criteria.

Standard Document Sections

1. Target Personas & User Journeys
2. Core Functional Requirements (with acceptance criteria)
3. Non-Functional Requirements (Security, Latency, Scale)
4. Scope Boundaries (Strictly IN scope vs OUT of scope for MVP)
5. Edge Cases & Validation Rules

AI Agent Usage: Used by coding agents during feature generation to guarantee all acceptance criteria pass before marking any feature as complete.

architecture.md

System Design & Models

Component topology, ASCII directory tree, route map, database schemas with indexes, and REST/WebSocket API contracts.

Standard Document Sections

1. High-Level Architecture & Component Map
2. Detailed Directory & Folder Structure (ASCII tree)
3. Routing Map & URL Structure (Pages, API routes, route guards)
4. Data Models & Entity Schemas (Fields, types, indexes)
5. API Contracts & Endpoint Specifications
6. Engineering Conventions & State Management Rules

AI Agent Usage: The single source of truth for file paths, database schemas, and API payload contracts. Prevents route drift and structural clutter.

design.md

Design Tokens & UI Hierarchy

Visual aesthetic direction, color palette tokens (hex codes), typography scale, component layout rules, and responsive breakpoints.

Standard Document Sections

1. Visual Aesthetic Direction (Theme, contrast, emotional tone)
2. Design Tokens & Color Palette (Hex codes for surfaces, borders, text)
3. Typography & Hierarchy (Font families, weights, scale)
4. Component Hierarchy & Key UI Layouts (Header, cards, tables)
5. Interactive States & Micro-animations (Hover, skeletons, toast)
6. Responsive Breakpoints & Mobile Adaptations

AI Agent Usage: Directs AI front-end generation to build cohesive, high-contrast user interfaces with standardized tokens rather than generic browser defaults.

executionPlan.md

Agent Task Roadmap

Phased task roadmap designed specifically for Agentic IDEs (Cursor, Antigravity, Claude Code) with actionable checkboxes and verification steps.

Standard Document Sections

Phase 1: Setup & Data Foundation
Phase 2: Core Business Logic & Gateways
Phase 3: Frontend Views & Interactive State
Phase 4: Integration Flows & Error Handling
Phase 5: Verification & Production Smoke Test

AI Agent Usage: Every task uses `- [ ] Task X.Y: ...`, `File: [path]`, and `- Verify: [command]`. Agents execute tasks sequentially without drifting or hallucinating.

Interactive Specification Explorer

Click through the live tabs below to inspect authentic markdown output generated by Archflow:

archflow-output /

Overview & Setup

# FlowForge - Real-Time Collaborative Architecture Suite

## 1. Executive Summary & Problem Solved
FlowForge provides distributed real-time diagramming for systems engineering teams. Eliminates architectural drift between whiteboard drawings and deployed infrastructure code.

## 2. Target Users & Value Proposition
- Staff & Lead Architects: Rapid high-level component topology modeling.
- AI Coding Agents: Contextual grounding to eliminate hallucinated routes or missing schemas.

## 3. Tech Stack Rationale
- Frontend: Next.js 16 (App Router), Tailwind CSS v4, HeroUI for high-contrast accessibility.
- Backend: Express 5 single-file micro-gateway with native MongoDB driver connection pooling.
- Auth: Better Auth with JWKS public key bridge for stateless token verification.
- Real-Time: WebSocket CRDT state sync engine with Redis channel replication.

## 4. Environment Setup
PORT=5000
MONGODB_URI=mongodb+srv://.../flowforge
BETTER_AUTH_URL=http://localhost:3000
JWKS_CACHE_TTL_MS=3600000

Active spec: projectOverview.mdFormat: Markdown / Agent-Ready

Agentic-IDE Prompting Patterns

Copy and paste these verified prompt structures into your AI coding tool to execute the suite smoothly:

Cursor (Composer / Agent)

Direct Composer to implement a specific phase using project context and architecture contracts.

@projectOverview.md @architecture.md @executionPlan.md Read executionPlan.md and implement Phase 1 tasks. Follow schemas in architecture.md strictly. Run verification commands after each task.

Claude Code CLI

Execute step-by-step tasks through the terminal agent with verified file boundaries.

claude "Read executionPlan.md and architecture.md. Implement Task 2.1 in Archflow-Server/src/index.ts, verify with the specified curl command, and check off the task."

Windsurf / Cascade

Autonomous multi-file execution across both client and server directories.

Execute all unchecked items in executionPlan.md. Ensure all client UI components conform to design.md tokens and backend handlers match architecture.md API contracts.

Google Antigravity / Agentic Workspace

Pair-programming prompt for complete milestone execution with automated verification.

Review projectOverview.md and requirements.md. Work through executionPlan.md Phase by Phase. Verify each step with npm run build or the designated test suite.

Production Engineering Standards

All blueprints follow strict, production-tested architecture guidelines:

Single-File Express 5 Gateways

Clean, high-throughput micro-gateways using the native MongoDB driver with connection caching, ping healthchecks, and structured error handling.

Better Auth & JWKS Verification

Stateless cryptographic authentication between Next.js frontend and Express backend using JWKS public key rotation.

Calibrated Contrast Tokens

Obsidian dark theme and warm paper light mode with balanced semantic surface, border, and text contrast tokens.

Checkbox-Driven Verification

Every task in executionPlan.md specifies an exact command or browser check so agents never complete unverified work.

3-Step Execution Workflow

How to take an Archflow blueprint from idea to working software:

Generate & Download

Input your requirements prompt or choose a community blueprint. Click Download Suite (.zip) to get all 5 markdown specifications.

Drop in Repo Root

Extract the 5 files directly into your project root folder so your AI coding assistant has immediate local workspace context.

Execute with Agent

Open Cursor Composer or Claude Code CLI and prompt: "Read executionPlan.md and implement Phase 1".

Ready to architect your next system?

Create a custom architecture suite or browse verified community blueprints.

Browse Blueprints Build Blueprint

Architecture Suite Overview

Zero Route Drift

Client fetchers and backend endpoints share exact parameter keys, query names, and JSON status contracts.

Deterministic Prompts

Every task in the execution plan has a designated file path and automated verification command.

Agent-First Markdown

Formatted cleanly in GitHub markdown with ASCII trees and code fences for instant LLM parsing.

# FlowForge - Real-Time Collaborative Architecture Suite ## 1. Executive Summary & Problem Solved FlowForge provides distributed real-time diagramming for systems engineering teams. Eliminates architectural drift between whiteboard drawings and deployed infrastructure code. ## 2. Target Users & Value Proposition - Staff & Lead Architects: Rapid high-level component topology modeling. - AI Coding Agents: Contextual grounding to eliminate hallucinated routes or missing schemas. ## 3. Tech Stack Rationale - Frontend: Next.js 16 (App Router), Tailwind CSS v4, HeroUI for high-contrast accessibility. - Backend: Express 5 single-file micro-gateway with native MongoDB driver connection pooling. - Auth: Better Auth with JWKS public key bridge for stateless token verification. - Real-Time: WebSocket CRDT state sync engine with Redis channel replication. ## 4. Environment Setup PORT=5000 MONGODB_URI=mongodb+srv://.../flowforge BETTER_AUTH_URL=http://localhost:3000 JWKS_CACHE_TTL_MS=3600000