# soma-smart/framefox architecture

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

- Interactive diagram: https://gitdiagram.com/soma-smart/framefox
- Repository: https://github.com/soma-smart/framefox

## Overview

##### Project Type and Purpose
- Framefox is an open-source Python web framework built on FastAPI. It provides:
- A clean MVC architecture (Controllers, Templates, Repositories)
- A CLI tool for project scaffolding and code generation
- Core services (routing, DI container, ORM, forms, security, tasks, websockets, debugging, profiling)
- Integration with SQLModel, Pydantic, Alembic, Jinja2
- The repository also includes an Astro-based documentation site under `docs/framefox`, but the heart of the system is the `framefox` Python package plus its `framefox/cli` and `framefox/core` modules.

##### File Structure
- Top-level:
- `.github`, CI/CD workflows, linters, tests, docs site, README, license, pyproject.toml
- `framefox/` – main Python package
- `framefox/cli` & `framefox/terminal` – interactive CLI commands and templates
- `framefox/core` – framework internals (kernel, DI, routing, controllers, events, middleware, ORM, security, forms, mail, tasks, websockets, templates, debugging/profiling)
- `framefox/tests` – unit and E2E tests
- Patterns:
- Layered MVC
- Service-provider / dependency-injection container
- Decorator-based routing & tasks
- Repository / Entity-Manager ORM
- Middleware pipeline
- Event dispatching/listening
- CLI code generators using Jinja2/Mako

##### README for Additional Insights
- Core features call out:
- FastAPI foundation → HTTP server and async support
- SQLModel & Pydantic → type-safe models and validation
- CLI → `framefox create`, `framefox run`, `framefox database`
- Security → CSRF, JWT, OAuth, firewall handlers
- Debugger & profiler UI → built-in error pages, profiling panels
- Background tasks → brokers (RabbitMQ, DB) and workers
- Encourages a standard MVC layout for user projects, but the framework itself must support and coordinate all moving parts.

##### Essential Architectural Elements
- Be detailed: show how each subsystem plugs into the Kernel
- Extension points (decorators, service definitions)
- Don’t over-abstract: include middleware, events, DI, CLI separately
- Both the runtime (request/task flows) and the developer experience (CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI & Code Generation"
        direction TB
        CLI["CLI Entry (cli.py)"]:::cli
        CLITerm["Terminal Module"]:::cli
    end

    %% Kernel & Bootstrap
    subgraph "Kernel & Bootstrap"
        direction TB
        KERN_APP["Application Bootstrap"]:::core
        KERN_CORE["Core Kernel"]:::core
    end

    %% HTTP & Routing
    subgraph "HTTP Server & Routing"
        direction TB
        HTTP["FastAPI Server"]:::core
        ROUTER["Router Module"]:::core
    end

    %% Middleware Pipeline
    subgraph "Middleware Pipeline"
        direction TB
        MIDDLE["Middleware Chain"]:::cross
    end

    %% Controllers & Views
    subgraph "Controllers & Views"
        direction TB
        CONTROLLER["Controller Modules"]:::core
        TEMPL["Template Renderer"]:::core
    end

    %% Dependency Injection
    subgraph "Dependency Injection"
        direction TB
        DI["Service Container"]:::core
    end

    %% ORM Layer
    subgraph "ORM & Migrations"
        direction TB
        ORM["Entity Manager & Repos"]:::core
    end

    %% Security Subsystem
    subgraph "Security Subsystem"
        direction TB
        SEC["Security Modules"]:::cross
    end

    %% Event Dispatcher
    subgraph "Event Dispatcher"
        direction TB
        EVENT["Event Dispatcher"]:::core
    end

    %% Task & Worker Subsystem
    subgraph "Task & Worker Subsystem"
        direction TB
        TASK["Task Manager"]:::task
    end

    %% Debug & Profiler
    subgraph "Debug & Profiler"
        direction TB
        DEBUG["Profiler & Debug UI"]:::cross
    end

    %% Mail & File Manager
    subgraph "Mail & File Management"
        direction TB
        MAIL["Mail Manager"]:::core
        FILEM["File Manager"]:::core
    end

    %% WebSocket Manager
    subgraph "WebSocket Manager"
        direction TB
        WS["WebSocket Manager"]:::core
    end

    %% External Systems
    subgraph "External Systems"
        direction TB
        DB[(Database)]:::external
        BROKER[(Message Broker)]:::external
        FS[(File System)]:::external
        OAUTH[(OAuth Providers)]:::external
    end

    %% Flow Relationships
    CLI -->|"bootstrap"| KERN_APP
    CLITerm -->|"bootstrap"| KERN_APP

    KERN_APP --> KERN_CORE
    KERN_CORE --> DI
    KERN_CORE --> ROUTER
    KERN_CORE --> MIDDLE
    KERN_CORE --> EVENT
    KERN_CORE --> ORM
    KERN_CORE --> SEC
    KERN_CORE --> TASK
    KERN_CORE --> DEBUG
    KERN_CORE --> MAIL
    KERN_CORE --> FILEM
    KERN_CORE --> WS

    HTTP --> MIDDLE
    MIDDLE --> ROUTER
    ROUTER --> CONTROLLER
    CONTROLLER --> DI
    DI --> ORM
    ORM --> DB
    CONTROLLER --> TEMPL
    TEMPL --> FS
    CONTROLLER --> TASK
    TASK --> BROKER
    BROKER --> TASK
    TASK --> WORKER[Worker Manager]
    WORKER --> DI
    MIDDLE --> DEBUG
    SEC --> MIDDLE
    EVENT --> CONTROLLER
    CONTROLLER --> EVENT
    MAIL --> FS
    WS --> CONTROLLER
    SEC --> OAUTH

    %% Click Events
    click CLI "https://github.com/soma-smart/framefox/blob/main/framefox/cli.py"
    click CLITerm "https://github.com/soma-smart/framefox/tree/main/framefox/terminal/"
    click KERN_APP "https://github.com/soma-smart/framefox/blob/main/framefox/application.py"
    click KERN_CORE "https://github.com/soma-smart/framefox/blob/main/framefox/core/kernel.py"
    click ROUTER "https://github.com/soma-smart/framefox/blob/main/framefox/core/routing/router.py"
    click MIDDLE "https://github.com/soma-smart/framefox/tree/main/framefox/core/middleware/"
    click CONTROLLER "https://github.com/soma-smart/framefox/tree/main/framefox/core/controller/"
    click TEMPL "https://github.com/soma-smart/framefox/blob/main/framefox/core/templates/template_renderer.py"
    click DI "https://github.com/soma-smart/framefox/blob/main/framefox/core/di/service_container.py"
    click ORM "https://github.com/soma-smart/framefox/blob/main/framefox/core/orm/entity_manager.py"
    click SEC "https://github.com/soma-smart/framefox/blob/main/framefox/core/security/token_manager.py"
    click EVENT "https://github.com/soma-smart/framefox/blob/main/framefox/core/events/event_dispatcher.py"
    click TASK "https://github.com/soma-smart/framefox/blob/main/framefox/core/task/task_manager.py"
    click DEBUG "https://github.com/soma-smart/framefox/blob/main/framefox/core/debug/profiler/profiler_controller.py"
    click MAIL "https://github.com/soma-smart/framefox/blob/main/framefox/core/mail/mail_manager.py"
    click FILEM "https://github.com/soma-smart/framefox/blob/main/framefox/core/file/file_manager.py"
    click WS "https://github.com/soma-smart/framefox/blob/main/framefox/core/websocket/web_socket_manager.py"
    click WORKER "https://github.com/soma-smart/framefox/blob/main/framefox/core/task/worker_manager.py"

    %% Styles
    classDef core fill:#D0E8FF,stroke:#0066CC,stroke-width:2px
    classDef cross fill:#E6FFE6,stroke:#33AA33,stroke-width:2px
    classDef cli fill:#FFE6CC,stroke:#CC6600,stroke-width:2px
    classDef task fill:#F0E6FF,stroke:#6600CC,stroke-width:2px
    classDef external fill:#EEEEEE,stroke:#888888,stroke-width:1px,stroke-dasharray: 5 5
    class CLI,CLITerm cli
    class KERN_APP,KERN_CORE,HTTP,ROUTER,CONTROLLER,TEMPL,DI,ORM,EVENT,MAIL,FILEM,WS core
    class MIDDLE,SEC,DEBUG cross
    class TASK,WORKER task
    class DB,BROKER,FS,OAUTH external
```
