# fastapi-mvc/example architecture

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

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

## Overview

##### Project type and purpose
- From the README and file layout, this is a template/example FastAPI-MVC service. It’s a backend web application (an “open-source tool” in the form of a microservice API) generated by fastapi-mvc.
- Purpose: Provide a well-structured, production-ready starting point for a FastAPI service with CLI support, ASGI/WSGI entrypoints, configuration, external dependencies (Redis, HTTP clients), and deployment artifacts (Docker, Helm charts, K8s manifests).

##### File structure
- Top-level:
- example/         ← main Python package
- charts/          ← Helm chart for Kubernetes
- manifests/       ← raw K8s resource YAMLs
- Dockerfile, Makefile, Vagrantfile, nix files
- docs/            ← Sphinx docs
- tests/           ← unit & integration tests
- example/app/ follows MVC:
- controllers/    ← request handlers
- views/          ← HTTP responses
- models/         ← Pydantic schemas
- exceptions/     ← HTTP error types
- utils/          ← Redis wrapper, aiohttp client
- router.py       ← consolidates endpoints
- asgi.py / wsgi.py ← application entrypoints
- example/cli/ contains CLI commands (serve, utils).
- example/config/ holds environment-driven settings (Gunicorn, Redis, application).
- build/, .github/, nix/ etc. support CI, dev-environment, container image builds.

##### README for additional insights
- The project is intended to demonstrate FastAPI-MVC conventions.
- CI workflows for linting, integration tests, docs.
- Deployment docs reference Helm, Kubernetes, Nix.

##### Elements
- HTTP request/response flow
- CLI → ASGI server startup
- Service → Redis / external HTTP
- CI/CD push → Docker build → Kubernetes deploy
- Code vs. infrastructure vs. external services vs. CI tools

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Codebase
    subgraph "Codebase"
        subgraph "example/app (API Service)"
            ASGI["ASGI Entrypoint\nasgi.py"]:::code
            WSGI["WSGI Entrypoint\nwsgi.py"]:::code
            Router["Router\nrouter.py"]:::code
            Controllers["Controllers\n/controllers/"]:::code
            Views["Views\n/views/"]:::code
            Models["Models\n/models/"]:::code
            Exceptions["Exceptions\n/exceptions/"]:::code
            subgraph "Utils"
                RedisAdapter["Redis Adapter\nredis.py"]:::code
                HTTPAdapter["HTTP Client Adapter\naiohttp_client.py"]:::code
            end
        end
        subgraph "example/cli (CLI)"
            CLI["CLI Interface\ncli.py"]:::code
            Serve["Serve Command\nserve.py"]:::code
            CLIUtils["CLI Utils\nutils.py"]:::code
        end
        subgraph "example/config (Config)"
            AppConf["Application Config\napplication.py"]:::code
            GunicornConf["Gunicorn Config\ngunicorn.py"]:::code
            RedisConf["Redis Config\nredis.py"]:::code
        end
    end

    %% Infrastructure and External Services
    subgraph "Infrastructure"
        Docker["Docker Build\nDockerfile\nMakefile\nbuild/image.sh"]:::infra
        Helm["Helm Chart\ncharts/example"]:::infra
        K8sYAML["K8s Manifests\nmanifests/"]:::infra
        RedisDep["Redis Operator\nall-redis-operator-resources.yaml"]:::external
    end

    %% CI/CD
    subgraph "CI/CD Workflows"
        GH_Main["main.yml"]:::ci
        GH_Int["integration.yml"]:::ci
        GH_Docs["docs.yml"]:::ci
        GH_Nix["nix.yml"]:::ci
        GH_Update["update-flake.yml"]:::ci
    end

    %% Documentation, DevEnv, Tests
    Docs["Sphinx Documentation\ndocs/"]:::docs
    NixEnv["Nix Development Environment\n*.nix"]:::devenv
    Tests["Tests\nunit/ integration/"]:::tests

    %% Runtime Data Flow
    CLI -->|"load config"| AppConf
    CLI -->|"start server"| ASGI
    CLI -->|"start server"| WSGI
    ASGI -->|"route requests"| Router
    Router --> Controllers
    Controllers --> Models
    Controllers --> Views
    Controllers --> RedisAdapter
    Controllers --> HTTPAdapter
    RedisAdapter --> RedisDep
    HTTPAdapter -->|"HTTP calls"| externalServices((Third-Party HTTP))
    Views -->|"HTTP response"| Router

    %% Deployment Flow
    GH_Main --> Docker
    Docker --> Helm
    Helm --> K8sYAML
    K8sYAML -->|"deploy pods"| APIServicePods((API Service Pods))
    APIServicePods --> RedisDep

    %% CI/CD Triggers
    GH_Int --> Tests
    GH_Docs --> Docs
    GH_Nix --> NixEnv
    GH_Update --> NixEnv

    %% Click Events
    click ASGI "https://github.com/fastapi-mvc/example/blob/master/example/app/asgi.py"
    click WSGI "https://github.com/fastapi-mvc/example/blob/master/example/app/wsgi.py"
    click Router "https://github.com/fastapi-mvc/example/blob/master/example/app/router.py"
    click Controllers "https://github.com/fastapi-mvc/example/tree/master/example/app/controllers/"
    click Views "https://github.com/fastapi-mvc/example/tree/master/example/app/views/"
    click Models "https://github.com/fastapi-mvc/example/tree/master/example/app/models/"
    click Exceptions "https://github.com/fastapi-mvc/example/tree/master/example/app/exceptions/"
    click RedisAdapter "https://github.com/fastapi-mvc/example/blob/master/example/app/utils/redis.py"
    click HTTPAdapter "https://github.com/fastapi-mvc/example/blob/master/example/app/utils/aiohttp_client.py"
    click CLI "https://github.com/fastapi-mvc/example/blob/master/example/cli/cli.py"
    click Serve "https://github.com/fastapi-mvc/example/blob/master/example/cli/serve.py"
    click CLIUtils "https://github.com/fastapi-mvc/example/blob/master/example/cli/utils.py"
    click AppConf "https://github.com/fastapi-mvc/example/blob/master/example/config/application.py"
    click GunicornConf "https://github.com/fastapi-mvc/example/blob/master/example/config/gunicorn.py"
    click RedisConf "https://github.com/fastapi-mvc/example/blob/master/example/config/redis.py"
    click RedisDep "https://github.com/fastapi-mvc/example/blob/master/manifests/all-redis-operator-resources.yaml"
    click Docker "https://github.com/fastapi-mvc/example/tree/master/Dockerfile"
    click Docker "https://github.com/fastapi-mvc/example/tree/master/Makefile"
    click Docker "https://github.com/fastapi-mvc/example/blob/master/build/image.sh"
    click Helm "https://github.com/fastapi-mvc/example/tree/master/charts/example/"
    click Helm "https://github.com/fastapi-mvc/example/tree/master/charts/example/templates/"
    click K8sYAML "https://github.com/fastapi-mvc/example/tree/master/manifests/"
    click GH_Main "https://github.com/fastapi-mvc/example/blob/master/.github/workflows/main.yml"
    click GH_Int "https://github.com/fastapi-mvc/example/blob/master/.github/workflows/integration.yml"
    click GH_Docs "https://github.com/fastapi-mvc/example/blob/master/.github/workflows/docs.yml"
    click GH_Nix "https://github.com/fastapi-mvc/example/blob/master/.github/workflows/nix.yml"
    click GH_Update "https://github.com/fastapi-mvc/example/blob/master/.github/workflows/update-flake.yml"
    click Docs "https://github.com/fastapi-mvc/example/tree/master/docs/"
    click NixEnv "https://github.com/fastapi-mvc/example/blob/master/default.nix"
    click NixEnv "https://github.com/fastapi-mvc/example/blob/master/shell.nix"
    click NixEnv "https://github.com/fastapi-mvc/example/blob/master/flake.nix"
    click NixEnv "https://github.com/fastapi-mvc/example/blob/master/flake.lock"
    click NixEnv "https://github.com/fastapi-mvc/example/blob/master/image.nix"
    click NixEnv "https://github.com/fastapi-mvc/example/blob/master/overlay.nix"
    click Tests "https://github.com/fastapi-mvc/example/tree/master/tests/unit/"
    click Tests "https://github.com/fastapi-mvc/example/tree/master/tests/integration/"

    %% Styles
    classDef code fill:#cce5ff,stroke:#000;
    classDef infra fill:#d4edda,stroke:#000;
    classDef external fill:#fff3cd,stroke:#000;
    classDef ci fill:#e2e3e5,stroke:#000;
    classDef docs fill:#fff5e6,stroke:#000;
    classDef devenv fill:#f5c6cb,stroke:#000;
    classDef tests fill:#d6d8db,stroke:#000;
```
