# spacelord16/modelhub architecture

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

- Interactive diagram: https://gitdiagram.com/spacelord16/modelhub
- Repository: https://github.com/spacelord16/modelhub

## Overview

##### Project Type & Purpose
- This is a full-stack web application called “Deep Learning Model Hub” for sharing, discovering, and deploying deep learning models.
- Frontend: Next.js + TypeScript + Tailwind CSS.
- Backend: FastAPI + SQLAlchemy + Pydantic + Alembic migrations.
- Storage: SQLite (or PostgreSQL) for metadata; filesystem or cloud for model files.
- Auth: JWT-based.

##### File Structure Analysis
- Top-level:
- backend/ → FastAPI service
- frontend/ → Next.js app
- backend/app layers:
- api/v1 (routers/controllers: auth, users, models)
- services (business logic)
- models (ORM) & schemas (Pydantic DTOs)
- core (config, DB session, security)
- utils/storage.py (file upload/download)
- backend/alembic: DB migrations
- CLI scripts: create_admin.py, get_token.py, reset_admin.py
- frontend/src/app: route-based pages (login, register, dashboard, models, upload, token debug)
- frontend components & contexts: UI primitives, navigation, ProtectedRoute, AuthContext, ThemeToggle.

##### Insights from README
- Key user flows: authentication, model browsing, upload, download, metrics, rating.
- API docs via FastAPI Swagger.
- Planned deployment features.

##### Elements
– Blue rectangles for services/servers
– Green rectangles for code modules (frontend components, backend layers)
- Annotations for key protocols (HTTP(S), SQL, JWT).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client / Frontend
    subgraph "Client / Frontend"
        Browser["Client (Browser/Mobile)"]:::external
        UI["Next.js App"]:::frontend
        subgraph "Pages (frontend/src/app)"
            Login["Login Page"]:::frontend
            Register["Register Page"]:::frontend
            Dashboard["Dashboard Page"]:::frontend
            Models["Models Listing"]:::frontend
            Upload["Model Upload"]:::frontend
            TokenDbg["Token Debug"]:::frontend
            APITest["API Test"]:::frontend
            AuthTest["Auth Test"]:::frontend
        end
        subgraph "Components & Contexts"
            UIComp["UI Components Folder"]:::frontend
            Nav["Navigation"]:::frontend
            Protect["ProtectedRoute"]:::frontend
            Providers["Providers"]:::frontend
            Theme["ThemeToggle"]:::frontend
            AuthCtx["AuthContext"]:::frontend
        end
    end

    %% Backend Service
    subgraph "Backend Service"
        Main["main.py (FastAPI Entry)"]:::backend
        subgraph "API Routers (backend/app/api/v1)"
            APIAgg["api.py (Router Aggregator)"]:::backend
            AuthR["auth.py"]:::backend
            UsersR["users.py"]:::backend
            ModelsR["models.py"]:::backend
        end
        Deps["deps.py"]:::backend
        subgraph "Services Layer"
            ModelSrv["model.py"]:::backend
        end
        subgraph "Data Models & Schemas"
            ORM1["user.py (ORM Model)"]:::backend
            ORM2["model.py (ORM Model)"]:::backend
            Schema1["user.py (Pydantic)"]:::backend
            Schema2["token.py"]:::backend
            Schema3["model.py"]:::backend
        end
        subgraph "Core Utilities"
            Config["config.py"]:::backend
            DBSession["database.py"]:::backend
            Security["security.py"]:::backend
        end
        Util["storage.py (File Storage)"]:::backend
        subgraph "Migrations (Alembic)"
            AlembicCfg["alembic.ini"]:::backend
            AlembicDir["alembic/"]:::backend
        end
    end

    %% Data Stores
    DB[(Database<br/>SQLite/PostgreSQL)]:::db
    Storage[(Model File Storage<br/>Local FS / S3)]:::storage

    %% Flows
    Browser --> UI
    UI -->|"HTTP(S) API"| Main
    Main --> APIAgg
    APIAgg --> AuthR
    APIAgg --> UsersR
    APIAgg --> ModelsR
    AuthR -->|depends on| Deps
    UsersR -->|depends on| Deps
    ModelsR -->|depends on| Deps
    ModelsR --> ModelSrv
    ModelSrv --> ORM2
    ModelSrv --> DBSession
    ModelSrv --> Util
    Deps --> DBSession
    Main -->|startup| Config
    DBSession --> DB
    Util --> Storage
    Main -.->|migrations| AlembicDir
    Main -.->|config| AlembicCfg

    %% Click Events Frontend
    click UI "https://github.com/spacelord16/modelhub/tree/main/frontend/"
    click Login "https://github.com/spacelord16/modelhub/blob/main/frontend/src/app/login/page.tsx"
    click Register "https://github.com/spacelord16/modelhub/blob/main/frontend/src/app/register/page.tsx"
    click Dashboard "https://github.com/spacelord16/modelhub/blob/main/frontend/src/app/dashboard/page.tsx"
    click Models "https://github.com/spacelord16/modelhub/blob/main/frontend/src/app/models/page.tsx"
    click Upload "https://github.com/spacelord16/modelhub/blob/main/frontend/src/app/upload/page.tsx"
    click TokenDbg "https://github.com/spacelord16/modelhub/blob/main/frontend/src/app/token-debug/page.tsx"
    click APITest "https://github.com/spacelord16/modelhub/blob/main/frontend/src/app/api-test/page.tsx"
    click AuthTest "https://github.com/spacelord16/modelhub/blob/main/frontend/src/app/auth-test/page.tsx"
    click UIComp "https://github.com/spacelord16/modelhub/tree/main/frontend/src/components/ui/"
    click Nav "https://github.com/spacelord16/modelhub/blob/main/frontend/src/components/Navigation.tsx"
    click Protect "https://github.com/spacelord16/modelhub/blob/main/frontend/src/components/ProtectedRoute.tsx"
    click Providers "https://github.com/spacelord16/modelhub/blob/main/frontend/src/components/Providers.tsx"
    click Theme "https://github.com/spacelord16/modelhub/blob/main/frontend/src/components/ThemeToggle.tsx"
    click AuthCtx "https://github.com/spacelord16/modelhub/blob/main/frontend/src/contexts/AuthContext.tsx"

    %% Click Events Backend
    click Main "https://github.com/spacelord16/modelhub/blob/main/backend/app/main.py"
    click APIAgg "https://github.com/spacelord16/modelhub/blob/main/backend/app/api/v1/api.py"
    click AuthR "https://github.com/spacelord16/modelhub/blob/main/backend/app/api/v1/auth.py"
    click UsersR "https://github.com/spacelord16/modelhub/blob/main/backend/app/api/v1/users.py"
    click ModelsR "https://github.com/spacelord16/modelhub/blob/main/backend/app/api/v1/models.py"
    click Deps "https://github.com/spacelord16/modelhub/blob/main/backend/app/api/deps.py"
    click ModelSrv "https://github.com/spacelord16/modelhub/blob/main/backend/app/services/model.py"
    click ORM1 "https://github.com/spacelord16/modelhub/blob/main/backend/app/models/user.py"
    click ORM2 "https://github.com/spacelord16/modelhub/blob/main/backend/app/models/model.py"
    click Schema1 "https://github.com/spacelord16/modelhub/blob/main/backend/app/schemas/user.py"
    click Schema2 "https://github.com/spacelord16/modelhub/blob/main/backend/app/schemas/token.py"
    click Schema3 "https://github.com/spacelord16/modelhub/blob/main/backend/app/schemas/model.py"
    click Config "https://github.com/spacelord16/modelhub/blob/main/backend/app/core/config.py"
    click DBSession "https://github.com/spacelord16/modelhub/blob/main/backend/app/core/database.py"
    click Security "https://github.com/spacelord16/modelhub/blob/main/backend/app/core/security.py"
    click Util "https://github.com/spacelord16/modelhub/blob/main/backend/app/utils/storage.py"
    click AlembicCfg "https://github.com/spacelord16/modelhub/blob/main/backend/alembic.ini"
    click AlembicDir "https://github.com/spacelord16/modelhub/tree/main/backend/alembic/"

    %% Styles
    classDef external fill:#f0f0f0,stroke:#333,stroke-width:1px
    classDef frontend fill:#e0ffe0,stroke:#2d8f2d,stroke-width:1px
    classDef backend fill:#e0f0ff,stroke:#236fa1,stroke-width:1px
    classDef db fill:#fff4c2,stroke:#c2a000,stroke-width:1px
    classDef storage fill:#f0f0f0,stroke:#999999,stroke-width:1px
```
