# bnbong/fastapi-fastkit architecture

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

- Interactive diagram: https://gitdiagram.com/bnbong/fastapi-fastkit
- Repository: https://github.com/bnbong/fastapi-fastkit

## Overview

##### Project type and purpose
- FastAPI-fastkit is a CLI tool (Python package) that scaffolds new FastAPI projects, manages virtual environments, installs dependencies, and provides template-based project creation.
- Its key features (from README) include commands like `init`, `startdemo`, `addroute`, `runserver`, and automatic template quality assurance.

##### File structure
- Top-level: `.github/`, `docs/`, `scripts/`, `src/fastapi_fastkit/`, `tests/`, config files (`pyproject.toml`, `Makefile`, etc.).
- `src/fastapi_fastkit/cli.py` and `__main__.py`: entrypoints for the CLI.
- `src/fastapi_fastkit/backend/`: inspector, transducer, package_managers (base, factory, pdm/poetry/pip/uv managers).
- `src/fastapi_fastkit/core/`: exceptions, settings.
- `src/fastapi_fastkit/utils/`: logging, main helpers.
- `src/fastapi_fastkit/fastapi_project_template/`: dozens of FastAPI project templates (async CRUD, Docker, PSQL-ORM, empty, etc.).
- `scripts/`: wrapper shell scripts for formatting, linting, testing.
- `tests/`: unit tests for each subsystem (backend, CLI, utils, templates).

##### Extract insights from the README
- The tool exposes multiple CLI commands, each wiring together backend components: CLI → Inspector → Transducer → PackageManager → filesystem & Python environment.
- Supports multiple “package manager” implementations via a factory (Strategy or Factory pattern).
- Templates are versioned and tested automatically (Template Quality Assurance).

##### Main components and their interactions
- Component A: **CLI Layer** (cli.py / __main__.py)
- Parses user input, dispatches to command handlers (`InitHandler`, `StartDemoHandler`, etc.).
- Component B: **Core Services**
- **Inspector**: Checks system state (Python version, existing venvs, OS specifics).
- **Transducer**: Orchestrates the flow: loads templates, renders files, calls package managers.
- **Settings / Exceptions**: Global configuration and error handling.
- Component C: **Package Manager Module**
- **Factory** selects one of {PipManager, PoetryManager, PDMManager, UVManager} based on CLI option.
- Each manager implements methods: `create_virtualenv()`, `install_dependencies()`, `run_server()`.
- Component D: **Template Store**
- A directory of templated projects (`fastapi-async-crud`, `fastapi-dockerized`, etc.).
- Template renderer: Reads `.tpl` files, substitutes placeholders, writes to new project dir.
- Component E: **Utilities**
- Logging (rich-powered output), file I/O helpers, version retrieval.
- Component F: **External Systems**
- OS filesystem, Python runtime, shell commands (pip, uvicorn, pdm, poetry), network for docs.

##### Architectural patterns and design principles
- **Separation of Concerns**: CLI parsing vs. business logic vs. file templating vs. environment management.
- **Factory Pattern**: `package_managers.factory` chooses the appropriate package manager.
- **Template Pattern**: Uniform interface for loading and rendering project templates.
- **Modular Layering**: CLI layer → Core services → Infrastructure (FS/Processes).

##### Putting it all together
- Off to the right: **Utilities** (purple) feeding cross-cutting concerns like logging/rich.
- At the bottom: **Automated QA Pipeline** showing GitHub Actions / tests running against templates.

##### Detail
- How new templates or package managers plug in.
- Core config (`core/settings.py`) driving behavior across components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User
    User["User / Terminal"]:::external

    %% CLI Layer
    subgraph "CLI Layer"
        CLI_MAIN["__main__.py"]:::cli
        CLI_CLI["cli.py"]:::cli
    end

    %% Core Services
    subgraph "Core Services"
        Inspector["Inspector"]:::core
        Transducer["Transducer"]:::core
        Settings["settings.py"]:::core
        Exceptions["exceptions.py"]:::core
    end

    %% Template Store
    subgraph "Template Store"
        Templates["fastapi_project_template/"]:::tmpl
    end

    %% Package Managers
    subgraph "Package Managers"
        Factory["factory.py"]:::pkg
        BasePM["base.py"]:::pkg
        Pip["PipManager"]:::pkg
        Poetry["PoetryManager"]:::pkg
        PDM["PDMManager"]:::pkg
        UV["UVManager"]:::pkg
    end

    %% External Systems
    subgraph "External Systems"
        OS["OS / Filesystem"]:::external
        Python["Python Runtime / venv"]:::external
        Shell["Shell Tools (pip, uvicorn, pdm, poetry)"]:::external
    end

    %% Utilities
    subgraph "Utilities"
        Logging["logging.py"]:::util
        Helpers["main.py"]:::util
    end

    %% Automated QA
    subgraph "Automated QA Pipeline"
        QA["GitHub Actions / Tests"]:::qa
    end

    %% Flows
    User -->|"run command"| CLI_MAIN
    CLI_MAIN -->|"import & dispatch"| CLI_CLI
    CLI_CLI -->|"parse args"| Inspector
    CLI_CLI -->|"dispatch"| Transducer
    Inspector -->|"validate env"| Exceptions
    CLI_CLI -->|"load config"| Settings

    Transducer -->|"load & render .tpl files"| Templates
    Transducer -->|"select manager"| Factory
    Factory -->|"implements interface"| BasePM
    Factory -->|"returns specific manager"| Pip
    Factory -->|"returns specific manager"| Poetry
    Factory -->|"returns specific manager"| PDM
    Factory -->|"returns specific manager"| UV

    Pip -->|"create venv & install deps"| Python
    Poetry -->|"create venv & install deps"| Python
    PDM -->|"create venv & install deps"| Python
    UV -->|"launch server"| Python

    Python --> OS
    Shell --> OS

    %% Utilities cross-cutting
    Logging -.->|logs| CLI_CLI
    Logging -.->|logs| Inspector
    Logging -.->|logs| Transducer
    Helpers -.->|helpers| CLI_CLI
    Helpers -.->|helpers| Transducer

    %% QA
    QA -->|tests templates| Templates
    QA -->|tests managers| Pip
    QA -->|tests managers| Poetry
    QA -->|tests managers| PDM
    QA -->|tests managers| UV

    %% Click Events
    click CLI_CLI "https://github.com/bnbong/fastapi-fastkit/blob/main/src/fastapi_fastkit/cli.py"
    click CLI_MAIN "https://github.com/bnbong/fastapi-fastkit/blob/main/src/fastapi_fastkit/__main__.py"
    click Inspector "https://github.com/bnbong/fastapi-fastkit/blob/main/src/fastapi_fastkit/backend/inspector.py"
    click Transducer "https://github.com/bnbong/fastapi-fastkit/blob/main/src/fastapi_fastkit/backend/transducer.py"
    click Settings "https://github.com/bnbong/fastapi-fastkit/blob/main/src/fastapi_fastkit/core/settings.py"
    click Exceptions "https://github.com/bnbong/fastapi-fastkit/blob/main/src/fastapi_fastkit/core/exceptions.py"
    click Factory "https://github.com/bnbong/fastapi-fastkit/blob/main/src/fastapi_fastkit/backend/package_managers/factory.py"
    click BasePM "https://github.com/bnbong/fastapi-fastkit/blob/main/src/fastapi_fastkit/backend/package_managers/base.py"
    click Pip "https://github.com/bnbong/fastapi-fastkit/blob/main/src/fastapi_fastkit/backend/package_managers/pip_manager.py"
    click Poetry "https://github.com/bnbong/fastapi-fastkit/blob/main/src/fastapi_fastkit/backend/package_managers/poetry_manager.py"
    click PDM "https://github.com/bnbong/fastapi-fastkit/blob/main/src/fastapi_fastkit/backend/package_managers/pdm_manager.py"
    click UV "https://github.com/bnbong/fastapi-fastkit/blob/main/src/fastapi_fastkit/backend/package_managers/uv_manager.py"
    click Templates "https://github.com/bnbong/fastapi-fastkit/tree/main/src/fastapi_fastkit/fastapi_project_template/"
    click Logging "https://github.com/bnbong/fastapi-fastkit/blob/main/src/fastapi_fastkit/utils/logging.py"
    click Helpers "https://github.com/bnbong/fastapi-fastkit/blob/main/src/fastapi_fastkit/utils/main.py"

    %% Styles
    classDef cli fill:#D0E8FF,stroke:#0366D6,color:#0366D6;
    classDef core fill:#DFFFE0,stroke:#28A745,color:#28A745;
    classDef pkg fill:#FFE4B5,stroke:#FF8C00,color:#FF8C00;
    classDef tmpl fill:#FFF8C6,stroke:#FFD700,color:#B8860B;
    classDef util fill:#F0E0FF,stroke:#6F42C1,color:#6F42C1;
    classDef external fill:#E0E0E0,stroke:#6A737D,color:#6A737D;
    classDef qa fill:#FDECEA,stroke:#CB2431,color:#CB2431;
```
