Skip to content

docs-overview.md

Latest commit

 

History

History
89 lines (63 loc) · 6.08 KB

docs-overview.md

File metadata and controls

89 lines (63 loc) · 6.08 KB

Documentation Architecture

This project uses a 3-tier documentation system that organizes knowledge by stability and scope, enabling efficient AI context loading and scalable development.

How the 3-Tier System Works

Tier 1 (Foundation): Stable, system-wide documentation that rarely changes - architectural principles, technology decisions, cross-component patterns, and core development protocols.

Tier 2 (Component): Architectural charters for major components - high-level design principles, integration patterns, and component-wide conventions without feature-specific details.

Tier 3 (Feature-Specific): Granular documentation co-located with code - specific implementation patterns, technical details, and local architectural decisions that evolve with features.

This hierarchy allows AI agents to load targeted context efficiently while maintaining a stable foundation of core knowledge.

Documentation Principles

  • Co-location: Documentation lives near relevant code
  • Smart Extension: New documentation files created automatically when warranted
  • AI-First: Optimized for efficient AI context loading and machine-readable patterns

Tier 1: Foundational Documentation (System-Wide)

  • Master Context - Essential for every session. Coding standards, security requirements, MCP server integration patterns, and development protocols
  • Project Structure - REQUIRED reading. Complete technology stack, file tree, and system architecture. Must be attached to Gemini consultations
  • System Integration - For cross-component work. Communication patterns, data flow, testing strategies, and performance optimization
  • Deployment Infrastructure - Infrastructure patterns. Containerization, monitoring, CI/CD workflows, and scaling strategies
  • Task Management - Session continuity. Current tasks, documentation system progress, and next session goals

Tier 2: Component-Level Documentation

Backend Components

  • Backend Context - Server implementation. API patterns, database integration, service architecture, and performance considerations
  • Worker Services - Background processing. Job queue patterns, scheduling, and async task management
  • Shared Libraries - Reusable code. Common utilities, shared types, and cross-component functionality

Frontend Components

  • Web Application - Client implementation. UI patterns, state management, routing, and user interaction patterns
  • Mobile Application - Mobile implementation. Platform-specific patterns, native integrations, and mobile optimizations
  • Admin Dashboard - Administrative interface. Permission patterns, admin workflows, and management tools

Infrastructure Components

  • Infrastructure Code - IaC patterns. Terraform/CloudFormation templates, resource definitions, and deployment automation
  • Monitoring Setup - Observability patterns. Metrics collection, alerting rules, and dashboard configurations

Tier 3: Feature-Specific Documentation

Granular CONTEXT.md files co-located with code for minimal cascade effects:

Backend Feature Documentation

  • Core Services - Business logic patterns. Service architecture, data processing, integration patterns, and error handling
  • API Layer - API patterns. Endpoint design, validation, middleware, and request/response handling
  • Data Layer - Data patterns. Database models, queries, migrations, and data access patterns
  • Authentication - Auth patterns. Authentication flows, authorization rules, session management, and security
  • Integrations - External services. Third-party API clients, webhook handlers, and service adapters

Frontend Feature Documentation

  • UI Components - Component patterns. Reusable components, styling patterns, accessibility, and composition strategies
  • State Management - State patterns. Global state, local state, data flow, and persistence strategies
  • API Client - Client patterns. HTTP clients, error handling, caching, and data synchronization
  • Routing - Navigation patterns. Route definitions, guards, lazy loading, and deep linking
  • Utilities - Helper functions. Formatters, validators, transformers, and common utilities

Shared Feature Documentation

  • Common Types - Type definitions. Shared interfaces, enums, and type utilities
  • Validation Rules - Validation patterns. Schema definitions, custom validators, and error messages
  • Constants - Shared constants. Configuration values, enums, and magic numbers
  • Utilities - Shared utilities. Cross-platform helpers, formatters, and common functions

Adding New Documentation

New Component

  1. Create /new-component/CONTEXT.md (Tier 2)
  2. Add entry to this file under appropriate section
  3. Create feature-specific Tier 3 docs as features develop

New Feature

  1. Create /component/src/feature/CONTEXT.md (Tier 3)
  2. Reference parent component patterns
  3. Add entry to this file under component's features

Deprecating Documentation

  1. Remove obsolete CONTEXT.md files
  2. Update this mapping document
  3. Check for broken references in other docs

This documentation architecture template should be customized to match your project's actual structure and components. Add or remove sections based on your architecture.