# sup3rus3r/nextapi-core architecture

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

- Interactive diagram: https://gitdiagram.com/sup3rus3r/nextapi-core
- Repository: https://github.com/sup3rus3r/nextapi-core

## Overview

NextAPI Core combines a Next.js/FastAPI starter with a CLI-driven full-stack module registry. The main user workflow is to register or sign in, use role-gated app pages and APIs, and extend the app by staging registry modules and syncing their routes, models, and navigation into the codebase. The README documents additional capabilities such as API-client credentials and Capacitor mobile packaging. Source excerpts are partial, so the graph omits uncertain internal wiring while retaining those documented product branches.

Main entry points: [`frontend/app/(app)/home/page.tsx`](https://github.com/sup3rus3r/nextapi-core/blob/main/frontend/app/(app)/home/page.tsx) (Auth and app pages), [`backend/main.py`](https://github.com/sup3rus3r/nextapi-core/blob/main/backend/main.py) (FastAPI endpoints), [`scripts/nextapi-cli/lib/registryClient.mjs`](https://github.com/sup3rus3r/nextapi-core/blob/main/scripts/nextapi-cli/lib/registryClient.mjs) (Registry client), [`scripts/nextapi-cli/cli.mjs`](https://github.com/sup3rus3r/nextapi-core/blob/main/scripts/nextapi-cli/cli.mjs) (NextAPI CLI)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Web app"]
  node_frontend_pages["Auth and app pages<br/>[page.tsx]"]
  node_nextauth["NextAuth credentials<br/>[auth.ts]"]
  node_registration_proxy["Registration proxy<br/>[route.ts]"]
  node_frontend_crypto["Server encryption<br/>[crypto-server.ts]"]
  node_rbac_routes["Role route policy<br/>[routes.ts]"]
  node_api_client["API client<br/>[api.ts]"]
  node_app_shell["Configurable app shell<br/>[app-shell.tsx]"]
end

subgraph group_backend["API and data"]
  node_backend_api["FastAPI endpoints<br/>[main.py]"]
  node_backend_auth["Token and API auth<br/>[auth.py]"]
  node_backend_crypto["Payload crypto<br/>[crypto_utils.py]"]
  node_schemas["Request validation<br/>[schemas.py]"]
  node_sqlite[("SQLite persistence<br/>[database.py]")]
  node_mongo[("Mongo persistence<br/>[database_mongo.py]")]
end

subgraph group_registry["Module registry"]
  node_registry_cli["NextAPI CLI<br/>[cli.mjs]"]
  node_add_command["Stage module<br/>[add.mjs]"]
  node_sync_command["Install and wire<br/>[sync.mjs]"]
  node_publish_command["Publish module<br/>[publish.mjs]"]
  node_registry_client["Registry client<br/>[registryClient.mjs]"]
  node_sync_resolver["Sync resolution<br/>[resolve.mjs]"]
end

subgraph group_delivery["Mobile platform"]
  node_capacitor["Capacitor app"]
end

node_user(("App user"))
node_backend_service(("FastAPI service"))
node_registry_service(("Module registry"))
node_ai_builder(("AI Builder"))
node_mobile_device(("Mobile device"))

node_user -->|"uses"| node_frontend_pages
node_frontend_pages -->|"signs in"| node_nextauth
node_nextauth -->|"encrypts credentials"| node_frontend_crypto
node_nextauth -->|"login request"| node_backend_service
node_frontend_pages -->|"registers"| node_registration_proxy
node_registration_proxy -->|"encrypts payload"| node_frontend_crypto
node_registration_proxy -->|"register request"| node_backend_service
node_backend_service -->|"routes requests"| node_backend_api
node_backend_api -->|"decrypts payload"| node_backend_crypto
node_backend_api -->|"validates"| node_schemas
node_backend_api -->|"checks credentials"| node_backend_auth
node_backend_api -->|"reads and writes"| node_sqlite
node_backend_api -->|"reads and writes"| node_mongo
node_frontend_pages -->|"checks access"| node_rbac_routes
node_frontend_pages -->|"renders within"| node_app_shell
node_frontend_pages -->|"requests data"| node_api_client
node_api_client -->|"API request"| node_backend_service
node_user -->|"runs commands"| node_registry_cli
node_registry_cli -->|"dispatches"| node_add_command
node_registry_cli -->|"dispatches"| node_sync_command
node_registry_cli -->|"dispatches"| node_publish_command
node_add_command -->|"fetches module"| node_registry_client
node_registry_client -->|"requests module"| node_registry_service
node_sync_command -->|"resolves staged modules"| node_sync_resolver
node_sync_command -->|"fetches dependencies"| node_registry_client
node_publish_command -->|"publishes module"| node_registry_client
node_registry_client -->|"transfers modules"| node_registry_service
node_ai_builder -.->|"generates modules"| node_registry_service
node_mobile_device -.->|"runs app"| node_capacitor
node_capacitor -.->|"uses JWT endpoints"| node_backend_service

click node_frontend_pages "https://github.com/sup3rus3r/nextapi-core/blob/main/frontend/app/(app)/home/page.tsx"
click node_nextauth "https://github.com/sup3rus3r/nextapi-core/blob/main/frontend/auth.ts"
click node_registration_proxy "https://github.com/sup3rus3r/nextapi-core/blob/main/frontend/app/api/backend/auth/register/route.ts"
click node_frontend_crypto "https://github.com/sup3rus3r/nextapi-core/blob/main/frontend/lib/crypto-server.ts"
click node_rbac_routes "https://github.com/sup3rus3r/nextapi-core/blob/main/frontend/config/routes.ts"
click node_api_client "https://github.com/sup3rus3r/nextapi-core/blob/main/frontend/lib/api.ts"
click node_backend_api "https://github.com/sup3rus3r/nextapi-core/blob/main/backend/main.py"
click node_backend_auth "https://github.com/sup3rus3r/nextapi-core/blob/main/backend/auth.py"
click node_backend_crypto "https://github.com/sup3rus3r/nextapi-core/blob/main/backend/crypto_utils.py"
click node_schemas "https://github.com/sup3rus3r/nextapi-core/blob/main/backend/schemas.py"
click node_sqlite "https://github.com/sup3rus3r/nextapi-core/blob/main/backend/database.py"
click node_mongo "https://github.com/sup3rus3r/nextapi-core/blob/main/backend/database_mongo.py"
click node_registry_cli "https://github.com/sup3rus3r/nextapi-core/blob/main/scripts/nextapi-cli/cli.mjs"
click node_add_command "https://github.com/sup3rus3r/nextapi-core/blob/main/scripts/nextapi-cli/commands/add.mjs"
click node_sync_command "https://github.com/sup3rus3r/nextapi-core/blob/main/scripts/nextapi-cli/commands/sync.mjs"
click node_publish_command "https://github.com/sup3rus3r/nextapi-core/blob/main/scripts/nextapi-cli/commands/publish.mjs"
click node_registry_client "https://github.com/sup3rus3r/nextapi-core/blob/main/scripts/nextapi-cli/lib/registryClient.mjs"
click node_sync_resolver "https://github.com/sup3rus3r/nextapi-core/blob/main/scripts/nextapi-cli/sync/resolve.mjs"
click node_app_shell "https://github.com/sup3rus3r/nextapi-core/blob/main/frontend/components/shell/app-shell.tsx"
click node_capacitor "https://github.com/sup3rus3r/nextapi-core/blob/main/frontend/capacitor.config.ts"

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_frontend_pages,node_nextauth,node_registration_proxy,node_frontend_crypto,node_rbac_routes,node_api_client,node_app_shell,node_user toneBlue
class node_backend_api,node_backend_auth,node_backend_crypto,node_schemas,node_sqlite,node_mongo toneAmber
class node_registry_cli,node_add_command,node_sync_command,node_publish_command,node_registry_client,node_sync_resolver,node_backend_service toneMint
class node_capacitor toneRose
class node_registry_service,node_ai_builder,node_mobile_device toneIndigo
```

## Components

### Web app

- [Auth and app pages](https://github.com/sup3rus3r/nextapi-core/blob/main/frontend/app/(app)/home/page.tsx): `frontend/app/(app)/home/page.tsx`
- [NextAuth credentials](https://github.com/sup3rus3r/nextapi-core/blob/main/frontend/auth.ts): `frontend/auth.ts`
- [Registration proxy](https://github.com/sup3rus3r/nextapi-core/blob/main/frontend/app/api/backend/auth/register/route.ts): `frontend/app/api/backend/auth/register/route.ts`
- [Server encryption](https://github.com/sup3rus3r/nextapi-core/blob/main/frontend/lib/crypto-server.ts): `frontend/lib/crypto-server.ts`
- [Role route policy](https://github.com/sup3rus3r/nextapi-core/blob/main/frontend/config/routes.ts): `frontend/config/routes.ts`
- [API client](https://github.com/sup3rus3r/nextapi-core/blob/main/frontend/lib/api.ts): `frontend/lib/api.ts`
- [Configurable app shell](https://github.com/sup3rus3r/nextapi-core/blob/main/frontend/components/shell/app-shell.tsx): `frontend/components/shell/app-shell.tsx`

### API and data

- [FastAPI endpoints](https://github.com/sup3rus3r/nextapi-core/blob/main/backend/main.py): `backend/main.py`
- [Token and API auth](https://github.com/sup3rus3r/nextapi-core/blob/main/backend/auth.py): `backend/auth.py`
- [Payload crypto](https://github.com/sup3rus3r/nextapi-core/blob/main/backend/crypto_utils.py): `backend/crypto_utils.py`
- [Request validation](https://github.com/sup3rus3r/nextapi-core/blob/main/backend/schemas.py): `backend/schemas.py`
- [SQLite persistence](https://github.com/sup3rus3r/nextapi-core/blob/main/backend/database.py): `backend/database.py`
- [Mongo persistence](https://github.com/sup3rus3r/nextapi-core/blob/main/backend/database_mongo.py): `backend/database_mongo.py`

### Module registry

- [NextAPI CLI](https://github.com/sup3rus3r/nextapi-core/blob/main/scripts/nextapi-cli/cli.mjs): `scripts/nextapi-cli/cli.mjs`
- [Stage module](https://github.com/sup3rus3r/nextapi-core/blob/main/scripts/nextapi-cli/commands/add.mjs): `scripts/nextapi-cli/commands/add.mjs`
- [Install and wire](https://github.com/sup3rus3r/nextapi-core/blob/main/scripts/nextapi-cli/commands/sync.mjs): `scripts/nextapi-cli/commands/sync.mjs`
- [Publish module](https://github.com/sup3rus3r/nextapi-core/blob/main/scripts/nextapi-cli/commands/publish.mjs): `scripts/nextapi-cli/commands/publish.mjs`
- [Registry client](https://github.com/sup3rus3r/nextapi-core/blob/main/scripts/nextapi-cli/lib/registryClient.mjs): `scripts/nextapi-cli/lib/registryClient.mjs`
- [Sync resolution](https://github.com/sup3rus3r/nextapi-core/blob/main/scripts/nextapi-cli/sync/resolve.mjs): `scripts/nextapi-cli/sync/resolve.mjs`

### Mobile platform

- [Capacitor app](https://github.com/sup3rus3r/nextapi-core/blob/main/frontend/capacitor.config.ts): `frontend/capacitor.config.ts`

### Other components

- **App user**
- **FastAPI service**
- **Module registry**
- **AI Builder**
- **Mobile device**

## Connections

- App user → Auth and app pages: uses
- Auth and app pages → NextAuth credentials: signs in
- NextAuth credentials → Server encryption: encrypts credentials
- NextAuth credentials → FastAPI service: login request
- Auth and app pages → Registration proxy: registers
- Registration proxy → Server encryption: encrypts payload
- Registration proxy → FastAPI service: register request
- FastAPI service → FastAPI endpoints: routes requests
- FastAPI endpoints → Payload crypto: decrypts payload
- FastAPI endpoints → Request validation: validates
- FastAPI endpoints → Token and API auth: checks credentials
- FastAPI endpoints → SQLite persistence: reads and writes
- FastAPI endpoints → Mongo persistence: reads and writes
- Auth and app pages → Role route policy: checks access
- Auth and app pages → Configurable app shell: renders within
- Auth and app pages → API client: requests data
- API client → FastAPI service: API request
- App user → NextAPI CLI: runs commands
- NextAPI CLI → Stage module: dispatches
- NextAPI CLI → Install and wire: dispatches
- NextAPI CLI → Publish module: dispatches
- Stage module → Registry client: fetches module
- Registry client → Module registry: requests module
- Install and wire → Sync resolution: resolves staged modules
- Install and wire → Registry client: fetches dependencies
- Publish module → Registry client: publishes module
- Registry client → Module registry: transfers modules
- AI Builder → Module registry: generates modules
- Mobile device → Capacitor app: runs app
- Capacitor app → FastAPI service: uses JWT endpoints