# allcode-1/pyarch architecture

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

- Interactive diagram: https://gitdiagram.com/allcode-1/pyarch
- Repository: https://github.com/allcode-1/pyarch

## Overview

PyArch is a CLI for creating and extending layered FastAPI projects. Users initialize a project, then use manifest-aware commands to add CRUD modules or JWT authentication, inspect project configuration, and manage PostgreSQL database lifecycle. The generation path runs from CLI commands through application services and generators to rendered templates and files; module and auth generation also update registration markers. The README documents these layers, while sampled source confirms several concrete calls. Some service and CLI relationships rely on the SOURCE INDEX rather than inspected implementations.

Main entry points: [`src/pyarch/cli/app.py`](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/cli/app.py) (Command router), [`src/pyarch/services/create_project.py`](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/services/create_project.py) (Project service), [`src/pyarch/generators/integration/auth.py`](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/generators/integration/auth.py) (Auth generator), [`src/pyarch/generators/common/renderer.py`](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/generators/common/renderer.py) (Template renderer)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI"]
  node_cli_app["Command router<br/>[app.py]"]
  node_cli_init["Init command<br/>[init.py]"]
  node_cli_generate["Module command<br/>[generate.py]"]
  node_cli_add["Integration command<br/>[add.py]"]
  node_cli_db["Database commands<br/>[db.py]"]
  node_cli_info["Info command<br/>[info.py]"]
end

subgraph group_services["Application services"]
  node_manifest["Project manifest<br/>[manifest.py]"]
  node_models["Project settings<br/>[models.py]"]
  node_create_project["Project service<br/>[create_project.py]"]
  node_create_module["Module service<br/>[create_module.py]"]
  node_add_integration["Integration service<br/>[add_integration.py]"]
  node_database_service["Database service<br/>[database.py]"]
end

subgraph group_generation["Project generation"]
  node_project_base["Base scaffold<br/>[base.py]"]
  node_project_layered["Layered scaffold<br/>[layered.py]"]
  node_module_generator["CRUD generator<br/>[layered.py]"]
  node_auth_generator["Auth generator<br/>[auth.py]"]
  node_templates["Project templates"]
end

subgraph group_shared["Generation support"]
  node_filesystem["File operations<br/>[filesystem.py]"]
  node_renderer["Template renderer<br/>[renderer.py]"]
  node_commands["Command runner<br/>[commands.py]"]
  node_gitignore["Ignore updates<br/>[gitignore.py]"]
end

node_user(("CLI user"))
node_generated_app["Generated FastAPI project"]

node_user -->|"runs commands"| node_cli_app
node_cli_app -->|"registers"| node_cli_init
node_cli_app -->|"registers"| node_cli_generate
node_cli_app -->|"registers"| node_cli_add
node_cli_app -->|"registers"| node_cli_db
node_cli_app -->|"registers"| node_cli_info
node_cli_init -->|"delegates"| node_create_project
node_cli_generate -->|"delegates"| node_create_module
node_cli_add -->|"delegates"| node_add_integration
node_cli_db -->|"delegates"| node_database_service
node_cli_info -->|"reads"| node_manifest
node_create_project -->|"writes"| node_manifest
node_create_project -->|"uses settings"| node_models
node_create_project -->|"creates scaffold"| node_project_base
node_create_project -->|"creates layers"| node_project_layered
node_create_module -->|"updates state"| node_manifest
node_create_module -->|"generates module"| node_module_generator
node_add_integration -->|"updates state"| node_manifest
node_add_integration -->|"generates auth"| node_auth_generator
node_database_service -->|"loads project"| node_manifest
node_database_service -->|"runs lifecycle"| node_commands
node_project_base -->|"renders files"| node_renderer
node_project_base -->|"initializes project"| node_commands
node_project_base -->|"updates ignores"| node_gitignore
node_project_layered -->|"renders layers"| node_renderer
node_project_layered -->|"installs dependencies"| node_commands
node_project_layered -->|"creates packages"| node_filesystem
node_module_generator -->|"renders CRUD"| node_renderer
node_module_generator -->|"registers routes"| node_filesystem
node_auth_generator -->|"renders auth"| node_renderer
node_auth_generator -->|"registers auth"| node_filesystem
node_auth_generator -->|"installs dependencies"| node_commands
node_auth_generator -->|"updates ignores"| node_gitignore
node_renderer -->|"loads"| node_templates
node_templates -->|"render into"| node_generated_app

click node_cli_app "https://github.com/allcode-1/pyarch/blob/main/src/pyarch/cli/app.py"
click node_cli_init "https://github.com/allcode-1/pyarch/blob/main/src/pyarch/cli/init.py"
click node_cli_generate "https://github.com/allcode-1/pyarch/blob/main/src/pyarch/cli/generate.py"
click node_cli_add "https://github.com/allcode-1/pyarch/blob/main/src/pyarch/cli/add.py"
click node_cli_db "https://github.com/allcode-1/pyarch/blob/main/src/pyarch/cli/db.py"
click node_cli_info "https://github.com/allcode-1/pyarch/blob/main/src/pyarch/cli/info.py"
click node_manifest "https://github.com/allcode-1/pyarch/blob/main/src/pyarch/config/manifest.py"
click node_models "https://github.com/allcode-1/pyarch/blob/main/src/pyarch/config/models.py"
click node_create_project "https://github.com/allcode-1/pyarch/blob/main/src/pyarch/services/create_project.py"
click node_create_module "https://github.com/allcode-1/pyarch/blob/main/src/pyarch/services/create_module.py"
click node_add_integration "https://github.com/allcode-1/pyarch/blob/main/src/pyarch/services/add_integration.py"
click node_database_service "https://github.com/allcode-1/pyarch/blob/main/src/pyarch/services/database.py"
click node_project_base "https://github.com/allcode-1/pyarch/blob/main/src/pyarch/generators/project/base.py"
click node_project_layered "https://github.com/allcode-1/pyarch/blob/main/src/pyarch/generators/project/layered.py"
click node_module_generator "https://github.com/allcode-1/pyarch/blob/main/src/pyarch/generators/module/layered.py"
click node_auth_generator "https://github.com/allcode-1/pyarch/blob/main/src/pyarch/generators/integration/auth.py"
click node_templates "https://github.com/allcode-1/pyarch/tree/main/src/pyarch/templates"
click node_filesystem "https://github.com/allcode-1/pyarch/blob/main/src/pyarch/generators/common/filesystem.py"
click node_renderer "https://github.com/allcode-1/pyarch/blob/main/src/pyarch/generators/common/renderer.py"
click node_commands "https://github.com/allcode-1/pyarch/blob/main/src/pyarch/generators/common/commands.py"
click node_gitignore "https://github.com/allcode-1/pyarch/blob/main/src/pyarch/generators/common/gitignore.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli_app,node_cli_init,node_cli_generate,node_cli_add,node_cli_db,node_cli_info,node_user toneBlue
class node_manifest,node_models,node_create_project,node_create_module,node_add_integration,node_database_service toneAmber
class node_project_base,node_project_layered,node_module_generator,node_auth_generator,node_templates,node_generated_app toneMint
class node_filesystem,node_renderer,node_commands,node_gitignore toneRose
```

## Components

### CLI

- [Command router](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/cli/app.py): `src/pyarch/cli/app.py`
- [Init command](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/cli/init.py): `src/pyarch/cli/init.py`
- [Module command](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/cli/generate.py): `src/pyarch/cli/generate.py`
- [Integration command](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/cli/add.py): `src/pyarch/cli/add.py`
- [Database commands](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/cli/db.py): `src/pyarch/cli/db.py`
- [Info command](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/cli/info.py): `src/pyarch/cli/info.py`

### Application services

- [Project manifest](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/config/manifest.py): `src/pyarch/config/manifest.py`
- [Project settings](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/config/models.py): `src/pyarch/config/models.py`
- [Project service](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/services/create_project.py): `src/pyarch/services/create_project.py`
- [Module service](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/services/create_module.py): `src/pyarch/services/create_module.py`
- [Integration service](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/services/add_integration.py): `src/pyarch/services/add_integration.py`
- [Database service](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/services/database.py): `src/pyarch/services/database.py`

### Project generation

- [Base scaffold](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/generators/project/base.py): `src/pyarch/generators/project/base.py`
- [Layered scaffold](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/generators/project/layered.py): `src/pyarch/generators/project/layered.py`
- [CRUD generator](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/generators/module/layered.py): `src/pyarch/generators/module/layered.py`
- [Auth generator](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/generators/integration/auth.py): `src/pyarch/generators/integration/auth.py`
- [Project templates](https://github.com/allcode-1/pyarch/tree/main/src/pyarch/templates): `src/pyarch/templates`

### Generation support

- [File operations](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/generators/common/filesystem.py): `src/pyarch/generators/common/filesystem.py`
- [Template renderer](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/generators/common/renderer.py): `src/pyarch/generators/common/renderer.py`
- [Command runner](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/generators/common/commands.py): `src/pyarch/generators/common/commands.py`
- [Ignore updates](https://github.com/allcode-1/pyarch/blob/main/src/pyarch/generators/common/gitignore.py): `src/pyarch/generators/common/gitignore.py`

### Other components

- **CLI user**
- **Generated FastAPI project**

## Connections

- CLI user → Command router: runs commands (evidence: `README.md`)
- Command router → Init command: registers (evidence: `src/pyarch/cli/app.py`)
- Command router → Module command: registers (evidence: `src/pyarch/cli/app.py`)
- Command router → Integration command: registers (evidence: `src/pyarch/cli/app.py`)
- Command router → Database commands: registers (evidence: `src/pyarch/cli/app.py`)
- Command router → Info command: registers (evidence: `src/pyarch/cli/app.py`)
- Init command → Project service: delegates (evidence: `src/pyarch/cli/init.py`)
- Module command → Module service: delegates (evidence: `src/pyarch/cli/generate.py`)
- Integration command → Integration service: delegates (evidence: `src/pyarch/cli/add.py`)
- Database commands → Database service: delegates (evidence: `src/pyarch/cli/db.py`)
- Info command → Project manifest: reads (evidence: `src/pyarch/cli/info.py`)
- Project service → Project manifest: writes (evidence: `src/pyarch/services/create_project.py`)
- Project service → Project settings: uses settings (evidence: `src/pyarch/services/create_project.py`)
- Project service → Base scaffold: creates scaffold (evidence: `src/pyarch/services/create_project.py`)
- Project service → Layered scaffold: creates layers (evidence: `src/pyarch/services/create_project.py`)
- Module service → Project manifest: updates state (evidence: `src/pyarch/services/create_module.py`)
- Module service → CRUD generator: generates module (evidence: `src/pyarch/services/create_module.py`)
- Integration service → Project manifest: updates state (evidence: `src/pyarch/services/add_integration.py`)
- Integration service → Auth generator: generates auth (evidence: `src/pyarch/services/add_integration.py`)
- Database service → Project manifest: loads project (evidence: `src/pyarch/services/database.py`)
- Database service → Command runner: runs lifecycle (evidence: `src/pyarch/services/database.py`)
- Base scaffold → Template renderer: renders files (evidence: `src/pyarch/generators/project/base.py`)
- Base scaffold → Command runner: initializes project (evidence: `src/pyarch/generators/project/base.py`)
- Base scaffold → Ignore updates: updates ignores (evidence: `src/pyarch/generators/project/base.py`)
- Layered scaffold → Template renderer: renders layers (evidence: `src/pyarch/generators/project/layered.py`)
- Layered scaffold → Command runner: installs dependencies (evidence: `src/pyarch/generators/project/layered.py`)
- Layered scaffold → File operations: creates packages (evidence: `src/pyarch/generators/project/layered.py`)
- CRUD generator → Template renderer: renders CRUD (evidence: `src/pyarch/generators/module/layered.py`)
- CRUD generator → File operations: registers routes (evidence: `src/pyarch/generators/module/layered.py`)
- Auth generator → Template renderer: renders auth (evidence: `src/pyarch/generators/integration/auth.py`)
- Auth generator → File operations: registers auth (evidence: `src/pyarch/generators/integration/auth.py`)
- Auth generator → Command runner: installs dependencies (evidence: `src/pyarch/generators/integration/auth.py`)
- Auth generator → Ignore updates: updates ignores (evidence: `src/pyarch/generators/integration/auth.py`)
- Template renderer → Project templates: loads (evidence: `src/pyarch/generators/common/renderer.py`)
- Project templates → Generated FastAPI project: render into (evidence: `README.md`)
