turtle-architecture

name	turtle-architecture
description	Use this when creating or updating architecture.md to define the system blueprint, including components, data flow, and architectural constraints. Typically used during initial project setup or when the system structure has changed significantly. Do not use for feature planning, implementation, debugging, or testing.

When to use

Use when creating or refreshing the system blueprint for the repository.

Inputs required

• current repository structure
• existing architecture.md if present
• major app components
• frameworks and services detected in repo
• known integrations and constraints

Always read

• agents.md
• repo_map.md

Output expected

• architecture.md
• concise system blueprint
• project structure
• runtime components
• request/data flow
• architecture principles
• risks, extension points, and open questions

Create or maintain the system architecture blueprint.

This is a living document designed to give agents and engineers a fast, accurate understanding of the codebase so they can safely navigate and modify it.

Before writing:

• check if architecture.md exists in the project root
• if it exists, read it and preserve its structure while extending it incrementally
• prefer editing existing sections over creating new ones; avoid duplication
• if it does not exist, create it

Rules

• do NOT overwrite existing valid content
• do NOT duplicate sections
• keep content concise and structured
• align with actual repository structure and patterns
• prefer repository facts over guesses
• if something is unclear, state it as an assumption or open question
• only document components that actually exist in the repo
• do NOT invent architecture, services, or components that do not exist
• do NOT assume future or planned features are implemented
• prioritize actual code and repository structure over documentation
• if architecture.md conflicts with code, treat code as source of truth

Save path: architecture.md

Overview

• What this system does
• Primary users
• Main business purpose

Project Structure

• High-level directory layout
• Major folders and responsibilities
• Important entry points

System Boundaries

• What is inside the system
• What is outside the system
• External services and APIs
• Third-party integrations

High-Level System Diagram

• Simple text diagram of major components and interactions

Architectural Principles

• Core engineering principles
• Patterns to prefer / avoid

Constraints and Non-Goals

Runtime Components

Request Flow

Data Flow

Data Layer

Database Schema (High Level)

Client Architecture

Server Architecture

API Structure

Authentication

Authorization

Security Model

Background Tasks

Performance Considerations

Observability and Operations

Build and Run

Environment Configuration

Deployment

Key Dependencies

Known Risks

Extension Points

Open Questions

Glossary / Acronyms