# fastapi/fastapi-cli architecture

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

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

## Overview

##### Project type and purpose
- This is a **command-line interface (CLI) tool** for discovering and running FastAPI applications.
- It provides two main commands: `fastapi dev` (development server with auto-reload) and `fastapi run` (production server).

##### File structure
- **src/fastapi_cli/**: the production code.
- `__main__.py` – entry point when you run `fastapi`.
- `cli.py` – command parsing and dispatch (`dev`, `run`).
- `discover.py` – logic to scan the filesystem, detect FastAPI app modules, and build import strings (e.g., `main:app`).
- `logging.py` – sets up and centralizes CLI logging.
- `exceptions.py` – custom exceptions for discovery and runtime errors.
- `utils/cli.py` – shared helper functions for argument normalization, path resolution, default values.
- **scripts/**: developer utilities for linting, formatting, and testing.
- **tests/**: unit and integration tests covering discovery, CLI behavior, and configuration edge cases.
- **.github/**: CI/CD workflows, issue templates, and Dependabot configuration.
- **pyproject.toml**, **requirements*.txt**, **pdm_build.py**: build and dependency definitions.

##### README for architecture hints
- FastAPI CLI uses **Uvicorn** under the hood to launch the ASGI server.
- Discovery: automatically finds the FastAPI `app` object in user code.
- Logs: prints structured logs (INFO, server messages, tips).

1. **User / Terminal** – the actor invoking `fastapi dev` or `fastapi run`.
2. **CLI Entry Point** (`__main__.py`)
3. **Argument Parser** (`cli.py`)
4. **Discovery Engine** (`discover.py`)
5. **Configuration & Utils** (`utils/cli.py`, `logging.py`)
6. **Uvicorn Server** (external library)
7. **User Application** (the FastAPI app module discovered on disk)
8. **File System** – where the user’s code resides
9. **Network Interface** – HTTP endpoints served by Uvicorn
1. Terminal → CLI Entry Point: user invokes command.
2. CLI Entry Point → Argument Parser: parse sub-commands & flags.
3. Argument Parser → Discovery Engine: supply target path(s).
4. Discovery Engine ↔ File System: scan directories, locate `app` object, handle exceptions.
5. Discovery Engine → CLI: returns import string (e.g., `main:app`).
6. CLI → Uvicorn: call `uvicorn.run(import_string, host, port, reload)` with appropriate flags.
7. Uvicorn ↔ User Application: import and serve the ASGI app.
8. Uvicorn → Network Interface: listens on TCP socket.
9. Logging flows from CLI & Uvicorn → Terminal.
c. Architectural patterns and principles
- **Separation of Concerns**: CLI parsing, discovery, logging, and server launch are modularized.
- **Dependency Injection**: Uvicorn configuration is passed in, not hard-coded.
- **Resilience**: custom exceptions in discovery to provide clear user feedback.
d. Key technologies and libraries
- Python 3.8+
- FastAPI CLI (this project)
- Uvicorn (ASGI server)
- Click or argparse (depending on implementation in `cli.py`)
- WatchFiles (for auto-reload)

- External libraries/services in another (e.g., green).
- User code and filesystem in a third (e.g., yellow).
- Rectangles for internal modules,

## Diagram (Mermaid)

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

    %% Core Modules
    subgraph "Core Modules"
        direction TB
        Main["CLI Entry Point\n(__main__.py)"]:::core
        CLI["Argument Parser & Dispatch\n(cli.py)"]:::core
        Disc["Discovery Engine\n(discover.py)"]:::core
        Utils["Shared CLI Utilities\n(utils/cli.py)"]:::util
        Logg["Logging Subsystem\n(logging.py)"]:::core
        Excp["Custom Exceptions\n(exceptions.py)"]:::core
    end

    %% External Dependencies
    subgraph "External Services & Libraries"
        direction TB
        Uvic["Uvicorn Server"]:::external
        Net["Network Interface"]:::external
    end

    %% User Code & Environment
    subgraph "User Environment"
        direction TB
        FS[(File System)]:::user
        UA["User Application\n(FastAPI app)"]:::user
    end

    %% Project Utilities
    subgraph "Project Utilities"
        direction TB
        Scripts["Developer Utility Scripts\n(scripts/)"]:::util
        Tests["Unit & Integration Tests\n(tests/)"]:::util
        CI["CI/CD Workflows\n(.github/workflows/)"]:::util
        subgraph "Build & Dependency Definitions"
            direction TB
            PyProj["pyproject.toml"]:::util
            ReqMain["requirements.txt"]:::util
            ReqTest["requirements-tests.txt"]:::util
            ReqGH["requirements-github-actions.txt"]:::util
            PDM["pdm_build.py"]:::util
        end
    end

    %% Flows
    Terminal -->|invokes command| Main
    Main -->|parse sub-commands & flags| CLI
    CLI -->|calls discovery| Disc
    Disc -->|scans directories| FS
    Disc -->|locates app & handles errors| Excp
    Disc -->|uses helpers| Utils
    Disc -->|returns import string| CLI
    CLI -->|uses logging| Logg
    CLI -->|launch server| Uvic
    Uvic -->|imports & serves ASGI app| UA
    Uvic -->|listens on socket| Net
    Uvic -->|emits server logs| Logg
    Logg -->|outputs logs| Terminal

    %% Click Events
    click Main "https://github.com/fastapi/fastapi-cli/blob/main/src/fastapi_cli/__main__.py"
    click CLI "https://github.com/fastapi/fastapi-cli/blob/main/src/fastapi_cli/cli.py"
    click Disc "https://github.com/fastapi/fastapi-cli/blob/main/src/fastapi_cli/discover.py"
    click Utils "https://github.com/fastapi/fastapi-cli/blob/main/src/fastapi_cli/utils/cli.py"
    click Logg "https://github.com/fastapi/fastapi-cli/blob/main/src/fastapi_cli/logging.py"
    click Excp "https://github.com/fastapi/fastapi-cli/blob/main/src/fastapi_cli/exceptions.py"
    click Scripts "https://github.com/fastapi/fastapi-cli/tree/main/scripts/"
    click Tests "https://github.com/fastapi/fastapi-cli/tree/main/tests/"
    click CI "https://github.com/fastapi/fastapi-cli/tree/main/.github/workflows/"
    click PyProj "https://github.com/fastapi/fastapi-cli/blob/main/pyproject.toml"
    click ReqMain "https://github.com/fastapi/fastapi-cli/blob/main/requirements.txt"
    click ReqTest "https://github.com/fastapi/fastapi-cli/blob/main/requirements-tests.txt"
    click ReqGH "https://github.com/fastapi/fastapi-cli/blob/main/requirements-github-actions.txt"
    click PDM "https://github.com/fastapi/fastapi-cli/blob/main/pdm_build.py"

    %% Styles
    classDef core fill:#D6EAF8,stroke:#2980B9,stroke-width:2px
    classDef external fill:#D5F5E3,stroke:#27AE60,stroke-width:2px
    classDef user fill:#FCF3CF,stroke:#B7950B,stroke-width:2px
    classDef util fill:#FADBD8,stroke:#C0392B,stroke-width:2px
```
