Accelint Architecture Doc

Architecture Doc

Generate or update a living ARCHITECTURE.md for the current codebase — a document that gives agents and engineers an instant, complete picture of how the system is structured, what it uses, and how it deploys.

NEVER Do When Writing Architecture Docs

• NEVER overwrite ARCHITECTURE.md without reading it first — existing sections contain human-authored context (deployment specifics, security decisions, roadmap notes) that codebase scanning cannot recover. Always read before touching.
• NEVER fabricate infrastructure details — if you cannot determine the cloud provider, deployment model, or data store from the codebase, mark it <!-- TODO: fill in --> rather than guessing. Wrong infrastructure docs cause real confusion during incidents.
• NEVER paste the entire directory tree verbatim — the Project Structure section should show meaningful architectural layers, not every file. Collapse noisy directories (node_modules, dist, .git, __pycache__) and annotate each entry with its architectural role.
• NEVER skip drift detection in refresh mode — scan the codebase for changed signals before running any interview. Asking questions about unchanged sections wastes the user's time.
• NEVER leave all 11 sections as `<!-- TODO -->` — scan aggressively first. Most sections can be at least partially filled through inference. A document full of TODOs appears complete but misleads every reader.
• NEVER document internal implementation details in the System Diagram (Section 2) — that section is a 10,000-foot view of components and data flow. Database schemas, function signatures, and module internals belong elsewhere.
• NEVER run discovery serially when subagents are available — Phase 1 spawns parallel subagents for different discovery domains. Serial scanning wastes time on codebases with many config files spread across directories.

Before Writing, Ask

Is this root or package level?

• Are we at the repo root or inside a monorepo package? Check for pnpm-workspace.yaml, turbo.json, nx.json, lerna.json, or workspaces field in package.json. If inside a package, check whether a root-level ARCHITECTURE.md already exists.
• Root-level docs cover the whole system — all services, shared infra, top-level architecture. Package-level docs focus on that package and reference the root.

Is this a create, restructure, or refresh?

• Does ARCHITECTURE.md already exist? If yes, read it before scanning — understand what's accurate vs. drifted.
• Does it follow the template? If not, proactively offer to restructure it before doing anything else.

What can I infer vs. what must I ask?

• Use parallel subagents for discovery. Spawn them simultaneously across discovery domains — don't scan serially.
• Reserve questions for genuine gaps — deployment specifics, roadmap items, and security decisions that aren't in the code.

---

Phases

Phase 0 — Scope and File State Detection

Run both steps before any scanning or interview. Announce findings and confirm mode with the user.

---

Step 1 — Monorepo Scope Check

Determine whether the current working directory is a monorepo root or a package inside a monorepo.

Monorepo signals to check:

If at the monorepo root:

• Generate a root-level ARCHITECTURE.md covering the full system — all services, shared infra, and how packages relate.
• Within Section 3 (Core Components), create a subsection per significant package rather than treating the repo as a single app.
• In Section 1 (Project Structure), show the workspace layout with each package's role annotated.

If inside a monorepo package: 1. Check whether a root-level ARCHITECTURE.md exists above the current directory. 2. If a root doc exists, read it and announce:

"I found a root-level ARCHITECTURE.md at [path]. I'll use it as context and generate a package-specific doc here that references it rather than duplicating shared infra."

The package-level doc should include a header reference:

   <!-- Part of monorepo: see [relative path to root ARCHITECTURE.md] for system-wide architecture -->

3. If no root doc exists, offer to generate it first or generate the package-level doc standalone. 4. Package-level docs focus on: this package's purpose, its internal structure, its dependencies on other packages, and any package-specific deployment or config details.

If not a monorepo: proceed normally — ARCHITECTURE.md covers the whole project.

---

Step 1.5 — Check for Related Documents

Before detecting ARCHITECTURE.md state, check for related onboarding documents:

1. Check for openspec/config.yml or openspec/config.yaml

• If exists: Read it to extract stack facts (runtime, frameworks, libraries, patterns)
• Use this info to pre-fill tech stack sections and avoid redundant scanning
• Note its existence for cross-referencing in generated doc
• Announce: "Found openspec/config.yml — I'll use it as the source of truth for stack facts and coding patterns."

This reduces scanning work and ensures consistency with the project's defined stack.

---

Step 2 — File Detection

Does ARCHITECTURE.md exist at the target location?
│
├── No → MODE 1: Create
│         Run Phase 1 → Phase 2 → Phase 3 in full.
│
└── Yes → Read the file fully, then assess:
          │
          ├── Empty or near-blank (< ~10 meaningful lines)?
          │     → MODE 1: Create (confirm first)
          │
          ├── Follows the template structure?
          │   (Has ≥3 of: ## 1. Project Structure, ## 2. High-Level
          │    System Diagram, ## 3. Core Components, ## 4. Data Stores,
          │    ## 6. Deployment & Infrastructure)
          │     → MODE 2: Refresh
          │       Drift detection + targeted questions for changed or
          │       missing sections only.
          │
          └── Has real content but does NOT follow the template?
                → MODE 3: Restructure (offer proactively — see below)

MODE 3: Restructure — When the file has real content in an unrecognised shape, surface this immediately and offer options before doing anything else:

"ARCHITECTURE.md exists but doesn't follow the standard template structure. I recommend restructuring it — this makes it consistent for agents and engineers onboarding to the codebase. How would you like to proceed?

>

(a) Restructure (recommended) — I'll import your existing content into the 11-section template, fill gaps with codebase scanning, and show a full preview before writing anything.

>

(b) Append — I'll add the missing template sections below your existing content without modifying what's already there.

>

(c) Dry run — I'll show exactly what the restructured doc would look like with no filesystem changes. Use this to evaluate fit before committing."

If (a) is chosen: carry all existing content forward into the appropriate template sections. Flag any content that doesn't map cleanly — present it to the user and ask where it belongs rather than silently dropping it.

---

Phase 1 — Parallel Discovery via Subagents

Spawn discovery subagents in parallel — don't scan serially. Each agent focuses on one domain and returns structured findings. Wait for all agents to complete, then merge results before Phase 2.

Spawn these agents simultaneously:

Agent A — Project Identity & Structure

• Read README.md, package.json / pyproject.toml / go.mod / Cargo.toml for project name and description
• List the top 2–3 levels of the directory tree (exclude node_modules, dist, .git, __pycache__, .next, build)
• Identify monorepo workspace packages and their roles
• Check for AGENTS.md or CLAUDE.md (record path if found — used in Phase 3)
• Return: project name, one-line purpose, annotated directory structure, agent doc path (or none)

Agent B — Tech Stack & Components

• package.json (frontend and backend deps), requirements.txt / pyproject.toml, go.mod, Cargo.toml, build.gradle
• Framework config files: next.config.*, vite.config.*, nuxt.config.*, angular.json, svelte.config.*
• Backend entry files: server.ts, app.py, main.go, Application.java, config/application.rb
• docker-compose.yml — services, ports, environment vars, inter-service dependencies
• Return: frontend tech, backend tech, key libraries, service list with ports

Agent C — Infrastructure, CI/CD & Deployment

• IaC: terraform/, pulumi/, cdk/, serverless.yml, k8s/ or kubernetes/
• Container config: Dockerfile* (per service), docker-compose.yml deployment config
• CI/CD: .github/workflows/, .circleci/, Jenkinsfile, .gitlab-ci.yml, Procfile
• Cloud signals: *.aws.json, .aws/, gcp/, azure/, base images in Dockerfiles
• Monitoring: Datadog, Sentry, Prometheus, Grafana, CloudWatch config or deps
• Return: cloud provider (inferred or unknown), key managed services, CI/CD platform, monitoring stack

Agent D — Data, Security & External APIs

• Data stores: prisma/schema.prisma, alembic/, migrations/, ORM config, DATABASE_URL in .env.example, Redis/Kafka/RabbitMQ deps
• Auth / security: auth middleware files, JWT/OAuth/SAML/OIDC deps, secrets manager (Vault, AWS Secrets Manager, Doppler), HTTPS config, WAF config
• External integrations: .env.example key prefixes (STRIPE_, SENDGRID_, TWILIO_, OPENAI_, etc.), SDK packages in deps
• Return: data store list (name, type, purpose), auth mechanism, external services list

Agent E — Testing & Code Quality (can run concurrently with the others)

• Test configs: jest.config.*, vitest.config.*, pytest.ini, pyproject.toml [tool.pytest], Playwright config, Cypress config
• Code quality: .eslintrc*, biome.json, .prettierrc*, mypy.ini, ruff.toml, sonar-project.properties
• Local setup: Makefile, CONTRIBUTING.md, docker-compose.yml dev targets
• Return: testing frameworks, code quality tools, local setup command

After all agents complete: merge their findings into a unified discovery map. Tag each field as INFERRED [source] or UNKNOWN. Fields tagged UNKNOWN become Phase 2 interview questions.

---

Phase 2 — Targeted Interview

Ask only about what discovery couldn't determine. Group related questions into natural conversational turns — never dump all questions at once.

Turn 1 — Gaps in Components (if services or components were unclear)

• Any services or components the directory structure doesn't make obvious?
• Any external services (third-party SaaS, internal shared platforms) not surfaced by the scan?

Turn 2 — Infrastructure & Deployment (only if cloud provider or deployment model is UNKNOWN)

• Cloud provider and key managed services used?
• How are services deployed? (VMs, containers, serverless, PaaS?)
• Monitoring and logging stack?

Turn 3 — Security (only if auth mechanism is UNKNOWN)

• Authentication mechanism? (OAuth2, JWT, session cookies, API keys, SSO?)
• Authorization model? (RBAC, ACLs, policy-based?)
• Any notable security tools or audit practices?

Turn 4 — Roadmap & Future Plans (always ask — cannot be inferred)

• Any planned architectural changes or migrations worth documenting?
• Known technical debt that affects the architecture?

Turn 5 — Identity & Glossary (if not found in README or package.json)

• Primary contact or team name?
• Any project-specific terms or acronyms that need defining?

---

Phase 3 — Preview and Write

1. Show a labeled preview of the complete ARCHITECTURE.md before writing. Mark each field:

• # inferred from [file] — for auto-detected values
• <!-- TODO: fill in --> — for unresolved fields

2. Ask: "Does this look right? Any sections to correct before I write?"

3. After confirmation, write to ARCHITECTURE.md at the target location (root or package dir), stripping inference source comments — they are for review only, not the final file. For openspec/config.yml references: only include them if the file actually exists (checked in Step 1.5). Do not add references to files that don't exist.

4. Update agent behavior doc if present — if Agent A found AGENTS.md or CLAUDE.md, check whether it references ARCHITECTURE.md. If not, append a reference block to help agents understand the system structure (see instructions below).

5. Print a brief summary: what was inferred, what was answered directly, which <!-- TODO --> sections still need human input.

---

Interaction Principles

• Parallel discovery. Spawn subagents for Phase 1 simultaneously — don't scan config files one-by-one.
• Scan first, ask second. Reserve interview questions for genuine gaps that subagents couldn't fill.
• Restructure by default. When a file doesn't follow the template, recommend restructuring and make it the easy choice — not option (c) buried at the bottom.
• Monorepo awareness. Root docs and package docs serve different audiences. Keep them scoped appropriately and reference each other.
• Announce what you found. In refresh mode, tell the user what drifted before asking anything.
• Preview before writing. Always show the full generated document and get confirmation before touching the filesystem.
• Infer before asking, ask before omitting. A doc with explicit <!-- TODO --> markers is actionable. A doc with missing sections silently misleads.
• Preserve human-authored content. In refresh mode, never silently remove content — surface it and confirm whether it's still accurate.
• Date every write. Set "Date of Last Update" in Section 10 to today's date on every write.

---

Output Template

Load references/template.md for the full 11-section ARCHITECTURE.md skeleton.

Monorepo package docs: Include the following immediately after the opening heading:

<!-- Part of monorepo: see [../../ARCHITECTURE.md](../../ARCHITECTURE.md) for system-wide architecture -->

Adjust the relative path to point at the actual root ARCHITECTURE.md.

---

Updating Agent Behavior Documents

ARCHITECTURE.md is a pure technical document about system structure and should not reference agent behavior files. However, agent behavior files (AGENTS.md or CLAUDE.md) should reference ARCHITECTURE.md since understanding system architecture may inform agent behavior.

After writing ARCHITECTURE.md, if Agent A found AGENTS.md or CLAUDE.md (check in that order):

1. Read the agent behavior file to check whether it already mentions ARCHITECTURE.md 2. If no reference exists, add this block near the top of the file (after any existing title/header, before main content):

## System Architecture

For technical architecture details (components, deployment, data stores, tech stack), see [ARCHITECTURE.md](./ARCHITECTURE.md).

3. If using CLAUDE.md and it simply points to AGENTS.md (e.g., @AGENTS.md), update AGENTS.md instead — don't modify the pointer file.

Changelog

All notable changes to this skill will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.0.0] - 2026-05-11

Added

• Initial skill release
• Phase 0 file state detection: Create vs. Refresh mode with import/append/dry-run options for unrecognised content shapes
• Phase 1 codebase scan table covering all 11 architecture.md sections with specific inference targets
• Phase 2 targeted interview (5 turns) covering only gaps the scan couldn't fill — deployment, security, roadmap, identity
• Phase 3 preview-before-write workflow with inference source annotations stripped from final output
• Drift detection table for refresh mode — 8 signal categories with specific file paths
• 6 anti-patterns with concrete WHY explanations (overwrite without reading, fabricate infrastructure, verbatim directory tree, skip drift detection, all-TODO document, implementation details in system diagram)
• references/template.md — full 11-section ARCHITECTURE.md skeleton with annotation guidance
• "Date every write" principle — always sets Section 10 date to today on each write

Rationale

• Modelled after accelint-onboard-agent and accelint-onboard-openspec patterns (Phase 0/1/2/3 structure, Mode 1/2/3 detection, infer-before-asking principle)
• Living document update path is the primary use case, not just initial creation — most invocations will be refreshes
• Codebase scanning is prioritised over interviewing to minimise user burden; questions are reserved for content that cannot be mechanically derived (roadmap, security decisions, deployment specifics not in IaC)

accelint-architecture-doc

Generate or update a living ARCHITECTURE.md document that gives agents and engineers a clear picture of how your system works.

Table of Contents

• Installation
• Quick Start
• What is this?
• How it works
• Usage modes
• Output format
• Advanced features
• Examples
• License

Installation

Install this skill using the skills CLI:

npx skills add https://github.com/accelint/agent-skills --skill accelint-architecture-doc

Once installed, invoke it in Claude Code with /accelint-architecture-doc.

Quick Start

The simplest use case - creating a new ARCHITECTURE.md:

/accelint-architecture-doc

That's it. The skill detects whether you need to create a new file, refresh an existing one, or restructure non-standard documentation. It scans your codebase, asks targeted questions about what it couldn't infer, shows you a preview, and writes the file only after confirmation.

What is accelint-architecture-doc?

This skill generates ARCHITECTURE.md files. Think of them as living documents that capture:

• Project structure and directory layout
• Tech stack (frameworks, languages, key libraries)
• System components (frontend, backend services, workers)
• Data stores (databases, caches, queues)
• External integrations and APIs
• Infrastructure, deployment, and monitoring setup
• Security model (auth, authorization, encryption)
• Testing and development environment
• Future roadmap and known technical debt

Two groups benefit from this:

AI agents get context about the codebase without scanning hundreds of files. Engineers get onboarding material and a single source of truth for architectural decisions.

How It Works

The skill operates in three phases:

Phase 0: Scope and File State Detection

Before scanning anything, the skill checks:

1. Monorepo detection - figures out if you're at the repo root or inside a package, then adjusts scope 2. File state - checks if ARCHITECTURE.md exists and whether it follows the standard template

Based on what it finds, it picks one of three modes:

Phase 1: Parallel Discovery

If the file needs creation or a full refresh, the skill spawns five parallel subagents to scan different discovery domains:

• Agent A - Project identity and structure
• Agent B - Tech stack and components
• Agent C - Infrastructure, CI/CD, and deployment
• Agent D - Data stores, security, and external APIs
• Agent E - Testing and code quality

Each agent scans specific files (package.json, docker-compose.yml, IaC configs, etc.) and returns structured findings. The skill merges these into a unified discovery map and tags each field as either INFERRED [source] or UNKNOWN.

Phase 2: Targeted Interview

The skill only asks about UNKNOWN fields. Questions come in groups:

1. Gaps in components (if the service list looks incomplete) 2. Infrastructure and deployment (if cloud provider or deployment model isn't clear) 3. Security (if auth mechanism is unknown) 4. Roadmap and future plans (always asked, since code can't tell us this) 5. Identity and glossary (if not found in README or package.json)

Well-documented codebases: 2-3 questions. Fresh projects with minimal config: 6-8 questions.

Phase 3: Preview and Write

You see the complete ARCHITECTURE.md before anything gets written. Inference sources are marked inline:

**Cloud Provider:** AWS # inferred from Dockerfile base image and .aws/ directory
**CI/CD Pipeline:** GitHub Actions # inferred from .github/workflows/deploy.yml
**Monitoring & Logging:** <!-- TODO: fill in -->

After you confirm, the skill writes the final file without the source annotations.

Usage Modes

Mode 1: Create (New File)

When: No ARCHITECTURE.md exists

What happens: 1. Full codebase scan via parallel subagents 2. Targeted interview for gaps 3. Preview with inference annotations 4. Write after confirmation

Typical time: 2-3 minutes with parallel discovery

Example:

/accelint-architecture-doc

Output:

No ARCHITECTURE.md found. Creating from scratch.
Spawning 5 discovery agents...
[Agents return findings]
I inferred most sections. I need to ask about:
1. Cloud provider (couldn't determine from codebase)
2. Monitoring stack (no observability config found)
3. Roadmap items
[Shows preview]
Does this look right?

Mode 2: Refresh (Update Existing)

When: ARCHITECTURE.md exists and follows the standard template

What happens: 1. Reads the existing file to understand current state 2. Runs drift detection (scans for new frameworks, added services, updated deployment configs) 3. Asks only about what changed 4. Shows preview with changes highlighted 5. Writes after you confirm

Takes about: 1-2 minutes

Example:

/accelint-architecture-doc

Output:

Found ARCHITECTURE.md. Running drift detection...
Detected changes:
- New service: worker/ directory with Dockerfile
- Added dependency: @prisma/client (database change?)
- New CI workflow: .github/workflows/test.yml

I'll update sections 3, 4, and 8. Sections 1, 2, 5, 6, 7, 9, 10, 11 appear accurate.
[Asks targeted questions]
[Shows preview]

Mode 3: Restructure (Import Existing Content)

When: ARCHITECTURE.md exists but doesn't follow the standard template

What happens: 1. Reads the existing file and notices it doesn't match the template 2. Offers three options:

• (a) Restructure - import existing content into the template and fill gaps
• (b) Append - add missing template sections below what's already there
• (c) Dry run - preview what the restructured doc would look like

3. If you choose restructure, it maps existing content to the right template sections 4. Flags any content that doesn't fit cleanly and asks where it should go 5. Fills gaps through scanning and interview 6. Shows preview before writing

Takes about: 3-4 minutes (includes mapping and gap-filling)

Example:

/accelint-architecture-doc

Output:

ARCHITECTURE.md exists but doesn't follow the standard template structure.
I recommend restructuring it — this makes it consistent for agents and engineers.

(a) Restructure (recommended) — import your existing content into the template
(b) Append — add missing sections below what's already there
(c) Dry run — show what restructured doc would look like

Which would you prefer?

Output Format

The skill generates an 11-section ARCHITECTURE.md following this structure:

1. Project Structure — annotated directory tree showing architectural layers 2. High-Level System Diagram — ASCII art block diagram of components and data flow 3. Core Components — detailed breakdown of frontend, backend services, and workers 4. Data Stores — databases, caches, queues, with purpose and key schemas 5. External Integrations / APIs — third-party services and integration methods 6. Deployment & Infrastructure — cloud provider, IaC, CI/CD, monitoring 7. Security Considerations — auth, authorization, encryption, security tools 8. Development & Testing Environment — local setup, test frameworks, code quality tools 9. Future Considerations / Roadmap — planned changes and known technical debt 10. Project Identification — name, repo URL, primary contact, last update date 11. Glossary / Acronyms — project-specific terms

Each section includes guidance comments in the template (loaded via references/template.md). The skill fills these sections through a combination of automated inference and targeted questions.

Advanced Features

Monorepo Support

The skill detects monorepo structure and adjusts scope:

At monorepo root:

• Generates a root-level ARCHITECTURE.md covering the full system
• Section 3 (Core Components) creates subsections per package
• Section 1 (Project Structure) shows workspace layout

Inside a monorepo package:

• Checks for root-level ARCHITECTURE.md and reads it for context
• Generates a package-specific doc that references the root doc
• Focuses on: package purpose, internal structure, dependencies on other packages

Drift Detection (Refresh Mode)

When refreshing an existing document, the skill scans for:

For each detected change, the skill asks questions to understand the context instead of blindly updating.

Agent Behavior Doc Integration

If the skill finds AGENTS.md or CLAUDE.md during discovery, it adds a reference block at the top of ARCHITECTURE.md:

> **Agent Behavior:** See [AGENTS.md](./AGENTS.md) for how AI agents should behave when working in this codebase.

This connects architectural context with behavioral instructions.

Inference Source Annotations

During preview, the skill marks how each field was determined:

**Technologies:** React 18, Next.js 14 # inferred from package.json and next.config.js
**Deployment:** <!-- TODO: fill in -->
**Monitoring:** Datadog # from user interview

These annotations help you verify accuracy before the skill writes anything. The final file doesn't include them.

Preservation of Human-Authored Content

In refresh mode, the skill won't silently remove content. If it finds sections that look human-written and can't verify their accuracy, it asks before changing them.

Examples

Example 1: New Next.js App

Input:

/accelint-architecture-doc

Context: Fresh Next.js 14 app with Prisma, deployed to Vercel, uses GitHub Actions for CI

Output (abbreviated):

# Architecture Overview

## 1. Project Structure

my-app/
├── app/              # Next.js 14 App Router pages and layouts
├── components/       # Reusable React components
├── lib/             # Utility functions and shared logic
├── prisma/          # Database schema and migrations
├── public/          # Static assets
└── .github/         # CI/CD workflows

## 2. High-Level System Diagram

[User] <--> [Next.js Frontend/Backend] <--> [PostgreSQL Database]

## 3. Core Components

### 3.1. Frontend

**Name:** Web Application

**Description:** Server-rendered React application with App Router for routing and layouts

**Technologies:** React 18, Next.js 14 App Router, TypeScript, Tailwind CSS

**Deployment:** Vercel

### 3.2. Backend Services

#### 3.2.1. Next.js API Routes

**Name:** API Service

**Description:** REST API via Next.js route handlers in app/api/

**Technologies:** Next.js 14, TypeScript, Prisma ORM

**Deployment:** Vercel (serverless functions)

## 4. Data Stores

### 4.1. Primary Database

**Name:** Application Database

**Type:** PostgreSQL 15 (via Supabase)

**Purpose:** Stores user data, content, and application state

**Key Schemas:** users, posts, sessions

...

Example 2: Refresh After Adding Service

Input:

/accelint-architecture-doc

Context: Existing ARCHITECTURE.md, added a background worker service

Output:

Found ARCHITECTURE.md. Running drift detection...

Detected changes:
- New directory: worker/ with Dockerfile and package.json
- Added dependency: bull (job queue library)
- New service in docker-compose.yml: redis

I'll update Section 3 (Core Components) to add the worker service
and Section 4 (Data Stores) to document Redis.

What does the worker service do?
> Processes video transcoding jobs asynchronously

[Shows preview with additions highlighted]
[User confirms]

Updated ARCHITECTURE.md:
- Added Section 3.2.2: Background Worker
- Added Section 4.2: Redis Job Queue

Example 3: Restructure Unstructured Doc

Input:

/accelint-architecture-doc

Context: ARCHITECTURE.md exists but is formatted as free-form prose, not the template structure

Output:

ARCHITECTURE.md exists but doesn't follow the standard template structure.
I recommend restructuring it — this makes it consistent for agents.

(a) Restructure (recommended)
(b) Append
(c) Dry run

> a

Reading existing content...

Found content that maps to:
- Section 1: directory structure notes
- Section 3: component descriptions
- Section 6: deployment details
- Unmapped: "Performance Considerations" section

Where should "Performance Considerations" go?
(a) Section 9 (Future Considerations / Roadmap)
(b) Section 8 (Development & Testing)
(c) New custom section

> a

[Continues with gap-filling interview]
[Shows preview]
[Writes restructured file]

License

Apache-2.0 - see LICENSE for details.

ARCHITECTURE.md Template

Use this exact structure. Fill every [placeholder] with content from codebase scanning or the interview. Replace unresolvable placeholders with <!-- TODO: fill in --> — never omit a section. Every section is load-bearing for agent and engineer onboarding.

---

# Architecture Overview

<!-- If openspec/config.yml exists, add this reference after the title: -->
<!-- > **Tech Stack:** See [openspec/config.yml](./openspec/config.yml) for detailed stack facts, coding patterns, and domain concepts. -->

This document serves as a critical, living reference designed to equip agents and engineers with a rapid and comprehensive understanding of the codebase's architecture. Update this document as the codebase evolves.

## 1. Project Structure

[Project Root]/
├── [directory]/      # [one-line architectural role]
│   ├── [subdir]/     # [role]
│   └── [subdir]/     # [role]
├── [directory]/      # [one-line architectural role]
├── .github/          # CI/CD configuration
├── .gitignore
├── README.md         # Project overview and quick-start
└── ARCHITECTURE.md   # This document

<!-- Collapse noisy directories (node_modules, dist, .git, __pycache__).
     Annotate each entry with its architectural role, not just its name. -->

## 2. High-Level System Diagram

<!-- If openspec/config.yml exists, add this intro: -->
<!-- > Complete stack facts and coding patterns are in [openspec/config.yml](./openspec/config.yml). This section provides deployment and runtime context. -->

<!-- Use ASCII art for a simple block diagram showing major components and data flow.
     Keep it at a 10,000-foot view — no schemas, no function signatures. -->

[User] <--> [Frontend] <--> [Backend Service] <--> [Database]
                        |
                        +--> [External API / Third-party Service]

## 3. Core Components

### 3.1. Frontend

**Name:** [e.g., Web App, Admin Dashboard, Mobile App]

**Description:** [Primary purpose and key functionalities. How do users interact with it?]

**Technologies:** [e.g., React 18, Next.js 14 App Router, TypeScript, Tailwind CSS]

**Deployment:** [e.g., Vercel, Netlify, S3 + CloudFront]

### 3.2. Backend Services

<!-- Repeat this block for each significant backend service. -->

#### 3.2.1. [Service Name]

**Name:** [e.g., API Service, Auth Service, Data Processing Worker]

**Description:** [What does this service do? What does it own?]

**Technologies:** [e.g., Node.js 20 + Express, Python 3.12 + FastAPI, Go 1.22]

**Deployment:** [e.g., AWS ECS Fargate, Kubernetes, AWS Lambda, Heroku]

<!-- Add more services as needed: 3.2.2., 3.2.3., etc. -->

## 4. Data Stores

### 4.1. [Primary Database]

**Name:** [e.g., Primary Application Database]

**Type:** [e.g., PostgreSQL 16, MongoDB 7, DynamoDB]

**Purpose:** [What data does it store? Why this type?]

**Key Schemas / Collections:** [e.g., users, organizations, sessions, events — names only, no full schema]

### 4.2. [Cache / Queue / Other]

**Name:** [e.g., Session Cache, Job Queue]

**Type:** [e.g., Redis 7, Kafka, RabbitMQ, SQS]

**Purpose:** [e.g., Session storage and rate limiting, async job processing]

<!-- Add more data stores as needed: 4.3., 4.4., etc. -->

## 5. External Integrations / APIs

| Service | Purpose | Integration Method |
|---------|---------|-------------------|
| [e.g., Stripe] | [e.g., Payment processing] | [e.g., REST API via SDK] |
| [e.g., SendGrid] | [e.g., Transactional email] | [e.g., REST API] |
| [e.g., AWS S3] | [e.g., File storage] | [e.g., AWS SDK] |

<!-- TODO: fill in if no external integrations found in codebase -->

## 6. Deployment & Infrastructure

**Cloud Provider:** [e.g., AWS, GCP, Azure, Fly.io, Railway, On-premise]

**Key Services Used:** [e.g., ECS, Lambda, RDS, S3, CloudFront, Route 53]

**CI/CD Pipeline:** [e.g., GitHub Actions — `.github/workflows/deploy.yml`]

**Monitoring & Logging:** [e.g., Datadog, Sentry, CloudWatch, Grafana + Prometheus]

## 7. Security Considerations

**Authentication:** [e.g., OAuth2 via Auth0, JWT (RS256), Session cookies (HttpOnly)]

**Authorization:** [e.g., RBAC with roles: admin, editor, viewer]

**Data Encryption:** [e.g., TLS 1.3 in transit, AES-256 at rest via RDS encryption]

**Key Security Tools / Practices:** [e.g., Dependabot, SAST via CodeQL, WAF via Cloudflare]

## 8. Development & Testing Environment

<!-- If openspec/config.yml exists, add this intro: -->
<!-- > Testing patterns and standards are defined in [openspec/config.yml](./openspec/config.yml); this section covers local setup and commands. -->

**Local Setup:** [Link to CONTRIBUTING.md, or brief steps: `cp .env.example .env && docker-compose up`]

**Testing Frameworks:** [e.g., Vitest + @testing-library/react, Pytest, Playwright for E2E]

**Code Quality Tools:** [e.g., ESLint + Prettier, Biome, mypy, Ruff, SonarCloud]

## 9. Future Considerations / Roadmap

<!-- Cannot be inferred — always ask the user. -->

- <!-- TODO: fill in planned architectural changes -->
- <!-- TODO: fill in known technical debt affecting architecture -->

## 10. Project Identification

**Project Name:** [Insert Project Name]

**Repository URL:** [Insert Repository URL]

**Primary Contact / Team:** [Insert Lead Developer or Team Name]

**Date of Last Update:** [YYYY-MM-DD]

## 11. Glossary / Acronyms

<!-- Define project-specific terms that would confuse a new engineer or agent.
     Skip common industry terms (REST, API, CI/CD) unless the project uses them non-standardly. -->

| Term | Definition |
|------|-----------|
| [Term or Acronym] | [Plain-English definition] |