# samratpro/fastadmin architecture

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

- Interactive diagram: https://gitdiagram.com/samratpro/fastadmin
- Repository: https://github.com/samratpro/fastadmin

## Overview

1. FastAdmin is split into two deployable runtimes: a Python backend in `api/` and a standalone Next.js admin UI in `admin/`. The repository also includes documentation, deployment helpers, and a public-app template, but those are support materials rather than the core runtime.

2. The backend is a FastAPI application entrypointed from `api/main.py`. It is organized Django-style into feature apps under `api/apps/*`, and those apps are auto-discovered at startup rather than wired together through a monolithic central module.

3. Each backend feature app owns its own boundary: `models.py` for domain data and `routers.py` for HTTP endpoints. The current included domains are `auth`, `blog`, `seo`, `settings`, `backup`, and `admin`, which makes the backend modular and easy to extend with new app folders.

4. Shared backend infrastructure lives in `api/core/` and `api/common/`. This includes configuration, database setup, security, dependency injection, registry logic for admin model registration, and the lightweight ORM layer used by application models.

5. The data layer is SQLite-first. The repository includes Alembic for migrations, but the README makes clear that new tables can be created automatically while schema changes to existing tables still require explicit migration or SQL steps. This matters for diagramming because the system is not relying on a fully managed ORM migration workflow alone.

6. Authentication is backend-driven and cookie-based. The API exposes login, logout, refresh, password reset, email verification, and `me` endpoints, and it stores JWTs in httpOnly cookies (`accessToken` and `refreshToken`). Swagger/OpenAPI docs are also available, but they are protected for superuser access.

7. The admin UI is a separate Next.js app using the App Router. Its main runtime surfaces are `login` and the `dashboard` area, with pages for models, individual model views, SEO, backup, and settings. This is the internal staff interface, not the public site.

8. The admin frontend talks to the API through a dedicated client layer in `admin/src/lib/api.ts` and uses client-side auth state in `admin/src/store/authStore.ts`. Route protection is handled in the UI via `ProtectedRoute`, so the browser experience depends on the backend session cookies plus frontend route guards.

9. The dashboard UI is model-centric. Components such as `ActionBar`, `DualListBox`, `EditorField`, `FiltersSidebar`, and `Fieldset` indicate that the admin is designed around CRUD, filtering, ordering, and content editing rather than generic page composition. There is also a small Next.js upload route in `admin/src/app/api/upload/route.ts`, which suggests some file handling happens inside the admin app boundary before or alongside API calls.

10. Extensibility is a first-class architectural concern. Backend models are meant to be registered into the admin system with `@register_admin`, and the `api/apps/admin/` plus `api/core/registry.py` pieces are the mechanism that turns backend models into admin-manageable resources.

11. Operationally, the repo is container-ready and CI-backed. There are Dockerfiles for both runtimes, a root `docker-compose.yml`, and a GitHub Actions workflow for validation. Node version files and npm config exist at the root and in `admin/`, showing that the frontend is treated as its own build target.

12. The `tutorials/` folder is part of the architecture story: it documents how to add apps, manage auth, run migrations, configure email, back up data, integrate SEO, and connect a separate public frontend. A reference public Next.js auth app lives under `tutorials/templates/public-auth-nextjs`, reinforcing the intended shape: public app and admin app both consume the same backend API, but remain separate frontends.

Main entry points: [`api/main.py`](https://github.com/samratpro/fastadmin/blob/master/api/main.py) (API entry), [`admin/src/lib/api.ts`](https://github.com/samratpro/fastadmin/blob/master/admin/src/lib/api.ts) (API client), [`admin/src/app/dashboard/page.tsx`](https://github.com/samratpro/fastadmin/blob/master/admin/src/app/dashboard/page.tsx) (Dashboard), [`api/apps/auth`](https://github.com/samratpro/fastadmin/tree/master/api/apps/auth) (Auth app)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_backend["Backend runtime"]
  node_api_main(("API entry<br/>FastAPI app<br/>[main.py]"))
  node_api_core["Core infra<br/>config/db/di"]
  node_api_registry["Admin registry<br/>resource registry<br/>[registry.py]"]
  node_api_security["Security<br/>auth helpers<br/>[security.py]"]
  node_api_orm["ORM layer<br/>model base<br/>[orm.py]"]
  node_api_auth["Auth app<br/>feature app"]
  node_api_blog["Blog app<br/>feature app"]
  node_api_seo["SEO app<br/>feature app"]
  node_api_settings["Settings app<br/>feature app"]
  node_api_backup["Backup app<br/>ops app"]
  node_api_admin["Admin API<br/>admin endpoints<br/>[routers.py]"]
  node_api_cli["User CLI<br/>maintenance tool<br/>[create_user.py]"]
end

subgraph group_admin["Admin runtime"]
  node_admin_shell(("UI shell<br/>Next.js app<br/>[layout.tsx]"))
  node_admin_login["Login<br/>auth page<br/>[page.tsx]"]
  node_admin_dash(("Dashboard<br/>staff workspace<br/>[page.tsx]"))
  node_admin_models["Models<br/>CRUD views<br/>[page.tsx]"]
  node_admin_seo["SEO panel<br/>admin page<br/>[page.tsx]"]
  node_admin_settings["Settings panel<br/>admin page<br/>[page.tsx]"]
  node_admin_backup["Backup panel<br/>admin page<br/>[page.tsx]"]
  node_admin_upload["Upload route<br/>file ingest<br/>[route.ts]"]
  node_admin_api["API client<br/>frontend client<br/>[api.ts]"]
  node_admin_store["Auth store<br/>client state<br/>[authStore.ts]"]
  node_admin_guard["Route guard<br/>protected route<br/>[ProtectedRoute.tsx]"]
end

subgraph group_support["Support & delivery"]
  node_docs["Docs<br/>guides<br/>[README.md]"]
  node_public_tpl["Public template<br/>Next.js template<br/>[page.tsx]"]
end

node_api_main -->|"boot"| node_api_core
node_api_main -->|"discover"| node_api_registry
node_api_main -->|"mount"| node_api_auth
node_api_main -->|"mount"| node_api_blog
node_api_main -->|"mount"| node_api_seo
node_api_main -->|"mount"| node_api_settings
node_api_main -->|"mount"| node_api_backup
node_api_main -->|"mount"| node_api_admin
node_api_auth -->|"uses"| node_api_security
node_api_auth -->|"models"| node_api_orm
node_api_blog -->|"models"| node_api_orm
node_api_seo -->|"models"| node_api_orm
node_api_settings -->|"models"| node_api_orm
node_api_registry -->|"publishes"| node_api_admin
node_api_admin -->|"manages"| node_api_auth
node_api_cli -->|"shares"| node_api_core
node_admin_shell -->|"routes"| node_admin_login
node_admin_shell -->|"routes"| node_admin_dash
node_admin_dash -->|"navigates"| node_admin_models
node_admin_dash -->|"navigates"| node_admin_seo
node_admin_dash -->|"navigates"| node_admin_settings
node_admin_dash -->|"navigates"| node_admin_backup
node_admin_guard -->|"checks"| node_admin_store
node_admin_store -->|"syncs"| node_admin_api
node_admin_models -->|"calls"| node_admin_api
node_admin_seo -->|"calls"| node_admin_api
node_admin_settings -->|"calls"| node_admin_api
node_admin_backup -->|"calls"| node_admin_api
node_admin_upload -->|"bridges"| node_admin_api
node_admin_api -->|"requests"| node_api_main
node_docs -.->|"explains"| node_api_main
node_docs -.->|"explains"| node_admin_shell
node_docs -.->|"templates"| node_public_tpl
node_public_tpl -->|"consumes"| node_api_main

click node_api_main "https://github.com/samratpro/fastadmin/blob/master/api/main.py"
click node_api_core "https://github.com/samratpro/fastadmin/tree/master/api/core"
click node_api_registry "https://github.com/samratpro/fastadmin/blob/master/api/core/registry.py"
click node_api_security "https://github.com/samratpro/fastadmin/blob/master/api/core/security.py"
click node_api_orm "https://github.com/samratpro/fastadmin/blob/master/api/common/orm.py"
click node_api_auth "https://github.com/samratpro/fastadmin/tree/master/api/apps/auth"
click node_api_blog "https://github.com/samratpro/fastadmin/tree/master/api/apps/blog"
click node_api_seo "https://github.com/samratpro/fastadmin/tree/master/api/apps/seo"
click node_api_settings "https://github.com/samratpro/fastadmin/tree/master/api/apps/settings"
click node_api_backup "https://github.com/samratpro/fastadmin/tree/master/api/apps/backup"
click node_api_admin "https://github.com/samratpro/fastadmin/blob/master/api/apps/admin/routers.py"
click node_api_cli "https://github.com/samratpro/fastadmin/blob/master/api/cli/create_user.py"
click node_admin_shell "https://github.com/samratpro/fastadmin/blob/master/admin/src/app/layout.tsx"
click node_admin_login "https://github.com/samratpro/fastadmin/blob/master/admin/src/app/login/page.tsx"
click node_admin_dash "https://github.com/samratpro/fastadmin/blob/master/admin/src/app/dashboard/page.tsx"
click node_admin_models "https://github.com/samratpro/fastadmin/blob/master/admin/src/app/dashboard/models/page.tsx"
click node_admin_seo "https://github.com/samratpro/fastadmin/blob/master/admin/src/app/dashboard/seo/page.tsx"
click node_admin_settings "https://github.com/samratpro/fastadmin/blob/master/admin/src/app/dashboard/settings/page.tsx"
click node_admin_backup "https://github.com/samratpro/fastadmin/blob/master/admin/src/app/dashboard/backup/page.tsx"
click node_admin_upload "https://github.com/samratpro/fastadmin/blob/master/admin/src/app/api/upload/route.ts"
click node_admin_api "https://github.com/samratpro/fastadmin/blob/master/admin/src/lib/api.ts"
click node_admin_store "https://github.com/samratpro/fastadmin/blob/master/admin/src/store/authStore.ts"
click node_admin_guard "https://github.com/samratpro/fastadmin/blob/master/admin/src/components/ProtectedRoute.tsx"
click node_docs "https://github.com/samratpro/fastadmin/blob/master/tutorials/README.md"
click node_public_tpl "https://github.com/samratpro/fastadmin/blob/master/tutorials/templates/public-auth-nextjs/src/app/login/page.tsx"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_api_main,node_api_core,node_api_registry,node_api_security,node_api_orm,node_api_auth,node_api_blog,node_api_seo,node_api_settings,node_api_backup,node_api_admin,node_api_cli toneBlue
class node_admin_shell,node_admin_login,node_admin_dash,node_admin_models,node_admin_seo,node_admin_settings,node_admin_backup,node_admin_upload,node_admin_api,node_admin_store,node_admin_guard toneAmber
class node_docs,node_public_tpl toneMint
```

## Components

### Backend runtime

FastAPI backend, feature apps, and shared server-side infrastructure.

- [API entry](https://github.com/samratpro/fastadmin/blob/master/api/main.py): FastAPI app · Backend startup and app wiring for the Python API runtime. · `api/main.py`
- [Core infra](https://github.com/samratpro/fastadmin/tree/master/api/core): config/db/di · Shared backend configuration, database setup, and dependency wiring. · `api/core`
- [Admin registry](https://github.com/samratpro/fastadmin/blob/master/api/core/registry.py): resource registry · Maps backend models into admin-manageable resources. · `api/core/registry.py`
- [Security](https://github.com/samratpro/fastadmin/blob/master/api/core/security.py): auth helpers · Backend security primitives used by authentication and session handling. · `api/core/security.py`
- [ORM layer](https://github.com/samratpro/fastadmin/blob/master/api/common/orm.py): model base · Lightweight ORM used by application models. · `api/common/orm.py`
- [Auth app](https://github.com/samratpro/fastadmin/tree/master/api/apps/auth): feature app · Login, logout, refresh, password reset, verification, and profile endpoints plus auth models. · `api/apps/auth`
- [Blog app](https://github.com/samratpro/fastadmin/tree/master/api/apps/blog): feature app · Content feature boundary with its own models and routes. · `api/apps/blog`
- [SEO app](https://github.com/samratpro/fastadmin/tree/master/api/apps/seo): feature app · SEO-related models and routes managed as a modular backend feature. · `api/apps/seo`
- [Settings app](https://github.com/samratpro/fastadmin/tree/master/api/apps/settings): feature app · Site configuration and settings models and routes. · `api/apps/settings`
- [Backup app](https://github.com/samratpro/fastadmin/tree/master/api/apps/backup): ops app · Backup-related backend endpoints and integration points. · `api/apps/backup`
- [Admin API](https://github.com/samratpro/fastadmin/blob/master/api/apps/admin/routers.py): admin endpoints · Backend admin endpoints that expose model registration and management capabilities. · `api/apps/admin/routers.py`
- [User CLI](https://github.com/samratpro/fastadmin/blob/master/api/cli/create_user.py): maintenance tool · Command-line helper for creating users and admin accounts. · `api/cli/create_user.py`

### Admin runtime

Standalone Next.js admin interface and its client-side state and API boundary.

- [UI shell](https://github.com/samratpro/fastadmin/blob/master/admin/src/app/layout.tsx): Next.js app · Top-level admin application shell and routing container. · `admin/src/app/layout.tsx`
- [Login](https://github.com/samratpro/fastadmin/blob/master/admin/src/app/login/page.tsx): auth page · Admin sign-in surface for session-based access. · `admin/src/app/login/page.tsx`
- [Dashboard](https://github.com/samratpro/fastadmin/blob/master/admin/src/app/dashboard/page.tsx): staff workspace · Main staff workspace that anchors the admin area. · `admin/src/app/dashboard/page.tsx`
- [Models](https://github.com/samratpro/fastadmin/blob/master/admin/src/app/dashboard/models/page.tsx): CRUD views · Model browser and per-model views for managing backend resources. · `admin/src/app/dashboard/models/page.tsx`
- [SEO panel](https://github.com/samratpro/fastadmin/blob/master/admin/src/app/dashboard/seo/page.tsx): admin page · Admin UI for SEO configuration and content controls. · `admin/src/app/dashboard/seo/page.tsx`
- [Settings panel](https://github.com/samratpro/fastadmin/blob/master/admin/src/app/dashboard/settings/page.tsx): admin page · Admin UI for site settings and operational configuration. · `admin/src/app/dashboard/settings/page.tsx`
- [Backup panel](https://github.com/samratpro/fastadmin/blob/master/admin/src/app/dashboard/backup/page.tsx): admin page · Admin UI for backup operations and status. · `admin/src/app/dashboard/backup/page.tsx`
- [Upload route](https://github.com/samratpro/fastadmin/blob/master/admin/src/app/api/upload/route.ts): file ingest · Small Next.js upload handler inside the admin boundary. · `admin/src/app/api/upload/route.ts`
- [API client](https://github.com/samratpro/fastadmin/blob/master/admin/src/lib/api.ts): frontend client · Dedicated browser-to-backend client used by the admin UI. · `admin/src/lib/api.ts`
- [Auth store](https://github.com/samratpro/fastadmin/blob/master/admin/src/store/authStore.ts): client state · Client-side authentication state and session awareness. · `admin/src/store/authStore.ts`
- [Route guard](https://github.com/samratpro/fastadmin/blob/master/admin/src/components/ProtectedRoute.tsx): protected route · UI-level route protection layered on top of backend cookies. · `admin/src/components/ProtectedRoute.tsx`

### Support & delivery

Documentation, public template, and container/CI assets that support the main runtimes.

- [Docs](https://github.com/samratpro/fastadmin/blob/master/tutorials/README.md): guides · Architecture, setup, migration, deployment, and feature guides. · `tutorials/README.md`
- [Public template](https://github.com/samratpro/fastadmin/blob/master/tutorials/templates/public-auth-nextjs/src/app/login/page.tsx): Next.js template · Reference public frontend template that consumes the same backend API. · `tutorials/templates/public-auth-nextjs/src/app/login/page.tsx`

## Connections

- API entry → Core infra: boot · Backend startup loads shared configuration, database, and dependencies.
- API entry → Admin registry: discover · Auto-discovers feature apps and registers admin resources.
- API entry → Auth app: mount · Wires the auth feature into the application.
- API entry → Blog app: mount · Wires the blog feature into the application.
- API entry → SEO app: mount · Wires the SEO feature into the application.
- API entry → Settings app: mount · Wires the settings feature into the application.
- API entry → Backup app: mount · Wires the backup feature into the application.
- API entry → Admin API: mount · Exposes admin-specific backend endpoints.
- Auth app → Security: uses · Authentication depends on backend security primitives.
- Auth app → ORM layer: models · Auth models are built on the shared ORM layer.
- Blog app → ORM layer: models · Blog data uses the shared ORM layer.
- SEO app → ORM layer: models · SEO data uses the shared ORM layer.
- Settings app → ORM layer: models · Settings data uses the shared ORM layer.
- Admin registry → Admin API: publishes · Registry makes backend models visible to admin management.
- Admin API → Auth app: manages · Admin endpoints operate on registered backend resources.
- User CLI → Core infra: shares · CLI helpers reuse backend configuration and persistence setup.
- UI shell → Login: routes · App shell contains the login surface.
- UI shell → Dashboard: routes · App shell contains the authenticated dashboard area.
- Dashboard → Models: navigates · Dashboard exposes model-centric management views.
- Dashboard → SEO panel: navigates · Dashboard exposes SEO controls.
- Dashboard → Settings panel: navigates · Dashboard exposes site settings controls.
- Dashboard → Backup panel: navigates · Dashboard exposes backup controls.
- Route guard → Auth store: checks · Route protection reads client auth state.
- Auth store → API client: syncs · Auth state is hydrated through the API client.
- Models → API client: calls · Model pages fetch and mutate data through the client layer.
- SEO panel → API client: calls · SEO page uses the dedicated API client.
- Settings panel → API client: calls · Settings page uses the dedicated API client.
- Backup panel → API client: calls · Backup page uses the dedicated API client.
- Upload route → API client: bridges · Upload handler sits beside the client-backed admin workflows.
- API client → API entry: requests · Admin UI talks to the FastAPI backend over the shared session boundary.
- Docs → API entry: explains · Documentation covers backend structure and runtime behavior.
- Docs → UI shell: explains · Documentation covers the admin UI and its workflows.
- Docs → Public template: templates · Docs include the separate public frontend template.
- Public template → API entry: consumes · Reference public app consumes the same backend API.