Documentation Index
Fetch the complete documentation index at: https://mintlify.com/davidbuenov/dbv-specs-ops/llms.txt
Use this file to discover all available pages before exploring further.
ARCHITECTURE.md is the technical blueprint of the project. It documents the stack, directory layout, key decisions, and — critically — the Agent Harness: the configuration that defines how the AI operates within the project’s boundaries. This file is the product of the /plan phase and must reflect the current state of the system at all times.
ARCHITECTURE.md documents what the system is today, not what you plan it to be someday. Writing aspirational architecture here confuses the AI, which reads this file as ground truth. Log future improvements in task.md as Technical Debt instead.
# 🏗 Technical Architecture: [Project Name]
> **Phase:** `/plan` (Technical Planning)
> **Status:** Draft / Validated
> **Last Revision:** [Date]
Section Reference
1. Tech Stack Table
Purpose: Provide a single-glance view of every technology layer and the reasoning behind each choice. Justifications are required — they give the AI (and future engineers) the context needed to make consistent decisions within the chosen constraints.
| Layer | Technology | Justification |
|---|
| Language | e.g., TypeScript 5.x | e.g., Static typing, mature ecosystem |
| Main Framework | e.g., Fastify / React | e.g., High performance / SPA without SSR complexity |
| Persistence | e.g., SQLite / PostgreSQL | e.g., No infrastructure for MVP / production-ready |
| Auth | e.g., JWT + bcrypt | e.g., Stateless, easy to scale |
| Testing | e.g., Vitest / Pytest | e.g., Fast, ESM-compatible |
| CI/CD | e.g., GitHub Actions | e.g., Integrated with the repository |
/build. If a change is needed, it must be documented as a Technical Decision in memory.md and approved before the AI proceeds.
2. Directory Structure
Purpose: Define the canonical layout that all generated files must follow. This prevents the AI from placing files in ad-hoc locations across sessions.
/
├── src/
│ ├── domain/ # Pure business logic (no external dependencies)
│ ├── application/ # Use cases and orchestration
│ ├── infrastructure/ # DB, external APIs, third-party services
│ └── interfaces/ # HTTP controllers, CLI, WebSocket
├── tests/
│ ├── unit/
│ └── integration/
├── docs/ # Project documentation (this directory)
└── [config files] # tsconfig, .env.example, etc.
For small projects, a single flat src/ folder is sufficient. Adapt this structure to the actual project size — over-engineering the directory layout for a small tool adds friction without benefit.
3. Key Technical Decisions
Purpose: Document the non-obvious choices that shape how the system is built. These entries act as lightweight Architecture Decision Records (ADRs) embedded in the architecture file itself.
Security
| Decision | Example value |
|---|
| Authentication | JWT with 1-hour expiration + refresh token in httpOnly cookie |
| Authorization | RBAC — roles defined in the database |
| Sensitive data | Environment variables via .env; never hardcoded in source |
Code Style
| Decision | Example value |
|---|
| Paradigm | Functional-first / Object-oriented |
| Conventions | See reference repo in MASTER_PROMPT.md |
| Max function complexity | 20 lines / cyclomatic complexity < 5 |
State Management
Document where state lives and how it flows through the system. Example:
Server state in the database; UI state in React Context (no Redux until scale demands it).
4. External Integrations Table
Purpose: Track every external service the project depends on, including rate limits and operational notes. The AI uses this table during /plan to flag integration risks.
| Service | Purpose | Notes / Limits |
|---|
| Stripe API | Payments | Rate limit: 100 req/s |
| SendGrid | Transactional email | Free tier: 100 emails/day |
5. Constraints & Technical Risks
Purpose: Document the hard boundaries the implementation must stay within, and the risks that have been identified but accepted or mitigated.
- **Constraint:** Deployment target is a 1 GB RAM VPS — optimize memory footprint.
- **Risk:** Third-party API dependency with no guaranteed SLA.
- **Mitigation:** Circuit breaker + 5-minute local cache.
6. Agent Harness
The Agent Harness is the most important section of ARCHITECTURE.md for AI-assisted development. It defines the complete infrastructure, context, tools, and constraints under which the AI agent operates. A well-configured harness produces safer, more consistent, and more autonomous AI behavior.
The AI is explicitly instructed to respect the harness configuration documented here. Any deviation — adding a new MCP server, changing sandboxing, or modifying guardrails — must be logged as a Technical Decision in memory.md and approved by the developer before proceeding.
6.1 Context Management (Static vs. Dynamic/Skills)
This sub-section defines what context the AI loads at startup versus what it retrieves on demand.
| Type | Description |
|---|
| Static Context | Global rule files and memory loaded at every session start. Examples: CLAUDE.md, GEMINI.md, memory.md. These are always in the AI’s context window. |
| Dynamic Context / Skills | Skill modules in skills/ or RAG pipelines loaded on demand by the agent. These are retrieved only when the relevant task requires them, keeping the baseline context window lean. |
6.2 Tools & MCP (Model Context Protocol)
This sub-section declares the MCP servers the agent is authorized to use and where their configuration lives.
| Field | Example |
|---|
| Required MCP Servers | filesystem, sqlite (structured data access), github (PR management) |
| Purpose | e.g., Direct connection to staging database for context queries |
| Configuration Files | .claude/settings.json, .windsurfrules, or equivalent |
6.3 Execution Environment (Sandboxing)
This sub-section defines the isolation boundaries within which the AI runs code.
### 3. Execution Environment (Sandboxing)
- **Isolation:** [Define the sandbox. E.g., Local Docker container, VM,
or local virtual environment (venv).]
- **Execution Limits:** [Token cost limits, timeout thresholds, or maximum
iteration count for async commands.]
MASTER_PROMPT.md mandates that Python projects always use a local venv/. The harness should document this explicitly and ensure venv/ is in .gitignore.
6.4 Deterministic Security Guardrails
This sub-section defines the automated checks that run deterministically — independently of the AI — to catch security issues that a generative model might introduce.
| Guardrail | Purpose |
|---|
| Linters | Enforce code style and catch common errors at pre-commit time |
| Pre-commit hooks with gitleaks | Scan for secrets (API keys, passwords, tokens) before they enter git history |
| SAST tools | Static Application Security Testing to catch vulnerability patterns |
| Commit/push policies | Block commits containing strings that resemble API keys or passwords |
6.5 External Agent Interface (Agent Readiness)
This sub-section is only required when Agent Readiness (Web): Yes is set in project.config.md. It documents the architecture for external agent discoverability.
| Field | What to document |
|---|
| Autodiscovery | How AI resources are exposed — e.g., HTTP Link headers injected by the web server pointing to agent cards and API catalog |
| Protocols & Cards | Location of agent.json and mcp.json in .well-known/. Support for the Model Context Protocol (MCP) and WebMCP on the client side |
| Content Format | Context optimization policies: dynamic Markdown negotiation for Accept: text/markdown headers and the structure of agent-skills/ |
Closing Instruction
The final line of ARCHITECTURE.md carries a binding instruction:
**AI Instruction:** Respect the decisions and harness configurations documented
here. If you need to deviate for a technical reason or want to suggest a new
MCP tool or Skill for the project, log it as a "Technical Decision" in
`memory.md` and obtain developer approval.
