# andrewhopper/dotai architecture

> Architecture diagram of the GitHub repository andrewhopper/dotai, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/andrewhopper/dotai
- Repository: https://github.com/andrewhopper/dotai

## Overview

##### Project type and purpose
- This is an open-source, tool-agnostic CLI application (“dotai”) built in Node.js.
- It scaffolds and enforces a standardized “.ai” directory structure and documentation workflow to accelerate AI-assisted projects.

##### File structure
- Top-level CLI:
- dotai/bin/dotai.js – the entry point installed globally
- src/commands – command modules (init.js, add.js, validate.js)
- src/utils – helper functions (createDirectoryStructure.js, copyTemplateFiles.js)
- Templates:
- src/templates – source templates mirror the “.ai” folder layout (0-ai-config, 1-context, 2-technical-design, 3-development, 4-acceptance-reports).
- Project docs and research:
- .ai – generated project documentation structure
- research – markdown research documents
- Config & packaging:
- package.json / manifest.json – dependency and CLI metadata
- .gitignore, LICENSE, readme.md

##### Key insights from README
- Purpose: standardized context management, automated docs & validation
- Workflow: bootstrapping → context definition → feature docs → implementation → validation cycles
- Features: interactive init, add new context sections, validate existing docs against rules

##### Main components and interactions
a. Components
- CLI Interface
- Command Loader (commander.js or similar)
- Command Handlers (init, add, validate)
- Template Engine & File System Layer (utils)
- Template Repository (src/templates)
- Generated Project Workspace (user’s .ai folder)
- Validation Rules (.cursorrules, .clinerules)
- External systems: NPM registry, Git
b. Relationships / Data Flow
1. User invokes `dotai <command>` via CLI.
2. CLI Interface parses args and dispatches to Command Loader.
3. Command Handler loads appropriate templates or rule sets.
4. Utils module reads/writes file system to scaffold or validate the target project.
5. Validation reads the `.ai` folder, applies rules defined in cursorrules/clinerules, emits reports.
6. Results are printed back to user.
c. Architectural patterns / design principles
- Command Pattern: each command is a discrete module that conforms to a shared interface.
- Template-Driven scaffolding: static templates + dynamic rendering.
- Separation of concerns: CLI parsing, template management, file I/O, validation logic are distinct layers.
- Config-over-code: rules and workflow steps are defined in markdown and config files, not hard-coded.
d. Key technologies
- Node.js, npm
- Commander.js or yargs (inferred CLI parser)
- Filesystem API (fs)
- JSON manifests (package.json, manifest.json)
- Markdown templates

##### Detailed elements
- Clear component names: “dotai CLI,” “init command,” “validate command,” “template store,” “.ai workspace.”

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User
    User["User"]:::external

    %% CLI Layer
    subgraph "CLI Layer"
        CLI["dotai CLI"]:::internal
        Loader["Command Loader & CLI Parsing"]:::internal
    end

    %% Commands
    subgraph "Command Handlers"
        Init["init command"]:::internal
        Add["add command"]:::internal
        Validate["validate command"]:::internal
    end

    %% Utils Layer
    subgraph "Utils Layer"
        CreateDir["createDirectoryStructure"]:::internal
        CopyTemplate["copyTemplateFiles"]:::internal
    end

    %% Template Repository
    subgraph "Template Repository" 
        Templates["src/templates"]:::static
        ConfigTpl["0-ai-config"]:::static
        ContextTpl["1-context"]:::static
        TechDesignTpl["2-technical-design"]:::static
        DevTpl["3-development"]:::static
        AcceptTpl["4-acceptance-reports"]:::static
    end

    %% Workspace
    subgraph "Generated Workspace"
        Workspace[".ai workspace"]:::static
        WS_Rules[".clinerules & .cursorrules"]:::static
    end

    %% External Systems
    subgraph "External Systems"
        NPM["NPM Registry"]:::external
        Git["Git"]:::external
    end

    %% Flows
    User -->|"invoke command"| CLI
    CLI -->|"parse args"| Loader
    Loader -->|"dispatch"| Init
    Loader -->|"dispatch"| Add
    Loader -->|"dispatch"| Validate

    Init -->|"scaffold"| CreateDir
    Init -->|"generate files"| CopyTemplate
    Add -->|"scaffold"| CopyTemplate
    Validate -->|"run validation"| CreateDir
    Validate -->|"run validation"| CopyTemplate

    CreateDir -->|"read templates"| Templates
    CopyTemplate -->|"copy from"| Templates
    CreateDir -->|"write to"| Workspace
    CopyTemplate -->|"write to"| Workspace

    Validate -->|"read rules from workspace"| WS_Rules
    Validate -->|"emit reports"| CLI
    CLI -->|"output results"| User

    %% Template sets relations
    Templates --> ConfigTpl
    Templates --> ContextTpl
    Templates --> TechDesignTpl
    Templates --> DevTpl
    Templates --> AcceptTpl

    %% External integrations
    CLI -->|"install"| NPM
    CLI -->|"commit docs"| Git

    %% Click Events
    click CLI "https://github.com/andrewhopper/dotai/blob/main/dotai/bin/dotai.js"
    click Loader "https://github.com/andrewhopper/dotai/blob/main/dotai/bin/dotai.js"
    click Init "https://github.com/andrewhopper/dotai/blob/main/dotai/src/commands/init.js"
    click Add "https://github.com/andrewhopper/dotai/blob/main/dotai/src/commands/add.js"
    click Validate "https://github.com/andrewhopper/dotai/blob/main/dotai/src/commands/validate.js"
    click CreateDir "https://github.com/andrewhopper/dotai/blob/main/dotai/src/utils/createDirectoryStructure.js"
    click CopyTemplate "https://github.com/andrewhopper/dotai/blob/main/dotai/src/utils/copyTemplateFiles.js"
    click Templates "https://github.com/andrewhopper/dotai/tree/main/dotai/src/templates"
    click ConfigTpl "https://github.com/andrewhopper/dotai/tree/main/dotai/src/templates/0-ai-config"
    click ContextTpl "https://github.com/andrewhopper/dotai/tree/main/dotai/src/templates/1-context"
    click TechDesignTpl "https://github.com/andrewhopper/dotai/tree/main/dotai/src/templates/2-technical-design"
    click DevTpl "https://github.com/andrewhopper/dotai/tree/main/dotai/src/templates/3-development"
    click AcceptTpl "https://github.com/andrewhopper/dotai/tree/main/dotai/src/templates/4-acceptance-reports"

    %% Styles
    classDef internal fill:#ADD8E6,stroke:#333,stroke-width:1px
    classDef static fill:#90EE90,stroke:#333,stroke-width:1px
    classDef external fill:#FFA500,stroke:#333,stroke-width:1px
```
