# nico0748/mana architecture

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

- Interactive diagram: https://gitdiagram.com/nico0748/mana
- Repository: https://github.com/nico0748/mana

## Overview

1. **What this repo is**
   - `doujin++` is a PWA that combines three domains: book inventory, doujin event shopping lists, and venue maps/navigation.
   - The codebase is split into a React/Vite frontend and an Express/Prisma/PostgreSQL backend, packaged to run together with Docker Compose.

2. **Runtime topology**
   - In production, the browser talks to the **frontend Nginx container** on one origin.
   - That Nginx layer serves the built SPA and reverse-proxies `/api/*` to the **backend Express container**.
   - The backend talks to **PostgreSQL** through Prisma.
   - This same-origin setup avoids CORS and is a key architectural boundary.

3. **Frontend subsystem**
   - The frontend is a React app organized by feature: `books`, `map`, `layout`, `ui`, and page-level routes such as `Books`, `ShoppingList`, `Map`, `Nav`, `Templates`, and `Tools`.
   - `frontend/src/lib/api.ts` is the main client boundary: all server communication is funneled through a typed REST wrapper.
   - Shared state and app-wide concerns are handled through contexts (`AuthContext`, `AppSettingsContext`) and hooks (`useBooks`, `useSync`, `useVenueRoute`).

4. **Backend subsystem**
   - `backend/src/index.ts` is the API composition point; it registers the domain routers.
   - The backend is split by resource/domain into `books`, `circles`, `circleItems`, `events`, `distributions`, `venueMaps`, and `sync`.
   - `backend/src/middleware/auth.ts` is the security boundary, and `backend/src/prisma.ts` holds the Prisma client singleton.

5. **Persistence model**
   - Prisma schema and migrations under `backend/prisma/` are the source of truth for the database shape.
   - PostgreSQL is the durable store for app state: books, circles, event/distribution data, venue map metadata, and related relations/status fields.
   - The backend runs `prisma migrate deploy` on startup, so schema changes are applied as part of deployment.

6. **Authentication boundary**
   - The app uses **Firebase Authentication** for user sign-in, including email/password and Google login.
   - The frontend manages login/session state, while the backend enforces access control through auth middleware.
   - This makes auth an external service boundary rather than something stored directly in PostgreSQL.

7. **Book-data flow**
   - The book area is centered around barcode scanning, book editing, list display, and detail views.
   - Book metadata is enriched via external book services: **OpenBD** is the primary ISBN lookup source, with **Google Books** as fallback.
   - The frontend’s book components and hooks call the backend API, which persists the normalized book data and relationships.

8. **Event, circle, and shopping-list flow**
   - The shopping-list side is modeled around circles, circle items, distributions, and events.
   - These domains are separate backend routes, which suggests the UI assembles shopping lists from event/circle/item state rather than from a single flat table.
   - The `sync` route indicates a dedicated consistency/synchronization path for client state updates.

9. **Venue-map and navigation flow**
   - Venue maps are a distinct subsystem: templates, schematic maps, route calculation, and navigation mode.
   - The frontend includes static venue data (`tokyoBigSight.ts`), route/pathfinding utilities (`dijkstra.ts`), and map import tooling.
   - Map images are stored in **Cloudflare R2**, and the README says uploads happen via **presigned PUT** directly from the browser, so the browser can upload without routing the file through the backend.

10. **Tooling and deployment**
   - Both frontend and backend use multi-stage Docker builds to keep runtime images small.
   - The frontend build outputs static files served by Nginx; the backend build produces a Node runtime image that launches the API after migrations.
   - CI/CD is driven by GitHub Actions (`.github/workflows/deploy.yml`) and deployment scripts, with environment configuration centralized in `.env.example`.

Main entry points: [`backend/src/index.ts`](https://github.com/nico0748/mana/blob/main/backend/src/index.ts) (API Entry), [`backend/src/prisma.ts`](https://github.com/nico0748/mana/blob/main/backend/src/prisma.ts) (Prisma Client), [`frontend/src/App.tsx`](https://github.com/nico0748/mana/blob/main/frontend/src/App.tsx) (React App), [`frontend/nginx.conf`](https://github.com/nico0748/mana/blob/main/frontend/nginx.conf) (Nginx)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_browser(("Browser<br/>client"))
  node_nginx["Nginx<br/>web proxy<br/>[nginx.conf]"]
  node_firebase(("Firebase Auth<br/>external service<br/>[firebase.ts]"))
end

subgraph group_frontend["Frontend"]
  node_frontend_app["React App<br/>SPA<br/>[App.tsx]"]
  node_frontend_api["API Client<br/>typed REST<br/>[api.ts]"]
  node_auth_ctx(("Auth State<br/>context<br/>[AuthContext.tsx]"))
  node_settings_ctx(("App Settings<br/>context"))
  node_books_ui["Books UI<br/>feature<br/>[BookList.tsx]"]
  node_shopping_ui["Shopping UI<br/>feature"]
  node_map_ui["Map UI<br/>feature<br/>[MapPage.tsx]"]
  node_route_logic["Route Logic<br/>pathfinding<br/>[dijkstra.ts]"]
  node_book_fetch["Book Enrichment<br/>external lookup<br/>[bookApi.ts]"]
end

subgraph group_backend["Backend"]
  node_api_index["API Entry<br/>Express app<br/>[index.ts]"]
  node_auth_mw["Auth Middleware<br/>security boundary<br/>[auth.ts]"]
  node_books_api["Books Route<br/>resource API<br/>[books.ts]"]
  node_shopping_api["Shopping Routes<br/>resource API<br/>[circles.ts]"]
  node_venue_api["Venue Maps<br/>resource API<br/>[venueMaps.ts]"]
  node_sync_api["Sync Route<br/>consistency API<br/>[sync.ts]"]
  node_prisma_client["Prisma Client<br/>db client<br/>[prisma.ts]"]
end

subgraph group_data["Data"]
  node_prisma_schema["Prisma Schema<br/>[schema.prisma]"]
  node_postgres[("PostgreSQL<br/>database")]
end

subgraph group_ops["Ops"]
  node_docker["Compose Builds<br/>deployment<br/>[docker-compose.yml]"]
  node_deploy["GitHub Actions<br/>ci/cd<br/>[deploy.yml]"]
end

node_browser -->|"loads app"| node_nginx
node_nginx -->|"serves SPA"| node_frontend_app
node_nginx -->|"proxies /api"| node_api_index
node_frontend_app -->|"uses"| node_frontend_api
node_frontend_app -->|"shares session"| node_auth_ctx
node_frontend_app -->|"shares prefs"| node_settings_ctx
node_books_ui -->|"reads/writes"| node_frontend_api
node_shopping_ui -->|"reads/writes"| node_frontend_api
node_map_ui -->|"calculates"| node_route_logic
node_books_ui -->|"enriches"| node_book_fetch
node_auth_ctx -->|"signs in"| node_firebase
node_api_index -->|"guards"| node_auth_mw
node_api_index -->|"mounts"| node_books_api
node_api_index -->|"mounts"| node_shopping_api
node_api_index -->|"mounts"| node_venue_api
node_api_index -->|"mounts"| node_sync_api
node_books_api -->|"persists"| node_prisma_client
node_shopping_api -->|"persists"| node_prisma_client
node_venue_api -->|"persists"| node_prisma_client
node_sync_api -->|"persists"| node_prisma_client
node_prisma_client -->|"uses schema"| node_prisma_schema
node_prisma_client -->|"connects"| node_postgres
node_docker -->|"packages"| node_nginx
node_docker -->|"packages"| node_api_index
node_deploy -->|"deploys"| node_docker

click node_nginx "https://github.com/nico0748/mana/blob/main/frontend/nginx.conf"
click node_frontend_app "https://github.com/nico0748/mana/blob/main/frontend/src/App.tsx"
click node_frontend_api "https://github.com/nico0748/mana/blob/main/frontend/src/lib/api.ts"
click node_auth_ctx "https://github.com/nico0748/mana/blob/main/frontend/src/contexts/AuthContext.tsx"
click node_settings_ctx "https://github.com/nico0748/mana/blob/main/frontend/src/contexts/AppSettingsContext.tsx"
click node_books_ui "https://github.com/nico0748/mana/blob/main/frontend/src/components/books/BookList.tsx"
click node_shopping_ui "https://github.com/nico0748/mana/blob/main/frontend/src/pages/ShoppingListPage.tsx"
click node_map_ui "https://github.com/nico0748/mana/blob/main/frontend/src/pages/MapPage.tsx"
click node_route_logic "https://github.com/nico0748/mana/blob/main/frontend/src/lib/dijkstra.ts"
click node_book_fetch "https://github.com/nico0748/mana/blob/main/frontend/src/lib/bookApi.ts"
click node_firebase "https://github.com/nico0748/mana/blob/main/frontend/src/lib/firebase.ts"
click node_api_index "https://github.com/nico0748/mana/blob/main/backend/src/index.ts"
click node_auth_mw "https://github.com/nico0748/mana/blob/main/backend/src/middleware/auth.ts"
click node_books_api "https://github.com/nico0748/mana/blob/main/backend/src/routes/books.ts"
click node_shopping_api "https://github.com/nico0748/mana/blob/main/backend/src/routes/circles.ts"
click node_venue_api "https://github.com/nico0748/mana/blob/main/backend/src/routes/venueMaps.ts"
click node_sync_api "https://github.com/nico0748/mana/blob/main/backend/src/routes/sync.ts"
click node_prisma_client "https://github.com/nico0748/mana/blob/main/backend/src/prisma.ts"
click node_prisma_schema "https://github.com/nico0748/mana/blob/main/backend/prisma/schema.prisma"
click node_docker "https://github.com/nico0748/mana/blob/main/docker-compose.yml"
click node_deploy "https://github.com/nico0748/mana/blob/main/.github/workflows/deploy.yml"

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_browser,node_nginx,node_firebase toneBlue
class node_frontend_app,node_frontend_api,node_auth_ctx,node_settings_ctx,node_books_ui,node_shopping_ui,node_map_ui,node_route_logic,node_book_fetch toneAmber
class node_api_index,node_auth_mw,node_books_api,node_shopping_api,node_venue_api,node_sync_api,node_prisma_client toneMint
class node_prisma_schema,node_postgres toneRose
class node_docker,node_deploy toneIndigo
```

## Components

### Runtime

Production request path and service boundaries

- **Browser**: client · End-user PWA entrypoint
- [Nginx](https://github.com/nico0748/mana/blob/main/frontend/nginx.conf): web proxy · Serves SPA and reverse-proxies API requests · `frontend/nginx.conf`
- [Firebase Auth](https://github.com/nico0748/mana/blob/main/frontend/src/lib/firebase.ts): external service · Sign-in provider for email/password and Google login · `frontend/src/lib/firebase.ts`

### Frontend

React/Vite PWA and browser-side logic

- [React App](https://github.com/nico0748/mana/blob/main/frontend/src/App.tsx): SPA · Main frontend application shell · `frontend/src/App.tsx`
- [API Client](https://github.com/nico0748/mana/blob/main/frontend/src/lib/api.ts): typed REST · Typed boundary for browser-to-server calls · `frontend/src/lib/api.ts`
- [Auth State](https://github.com/nico0748/mana/blob/main/frontend/src/contexts/AuthContext.tsx): context · Session and login state management · `frontend/src/contexts/AuthContext.tsx`
- [App Settings](https://github.com/nico0748/mana/blob/main/frontend/src/contexts/AppSettingsContext.tsx): context · Global app preferences and shared settings · `frontend/src/contexts/AppSettingsContext.tsx`
- [Books UI](https://github.com/nico0748/mana/blob/main/frontend/src/components/books/BookList.tsx): feature · Barcode scan, edit, list, and detail views · `frontend/src/components/books/BookList.tsx`
- [Shopping UI](https://github.com/nico0748/mana/blob/main/frontend/src/pages/ShoppingListPage.tsx): feature · Event, circle, and list assembly screens · `frontend/src/pages/ShoppingListPage.tsx`
- [Map UI](https://github.com/nico0748/mana/blob/main/frontend/src/pages/MapPage.tsx): feature · Venue schematic maps and navigation pages · `frontend/src/pages/MapPage.tsx`
- [Route Logic](https://github.com/nico0748/mana/blob/main/frontend/src/lib/dijkstra.ts): pathfinding · Venue route calculation and navigation helpers · `frontend/src/lib/dijkstra.ts`
- [Book Enrichment](https://github.com/nico0748/mana/blob/main/frontend/src/lib/bookApi.ts): external lookup · ISBN metadata lookup via OpenBD and Google Books · `frontend/src/lib/bookApi.ts`

### Backend

Express API and persistence

- [API Entry](https://github.com/nico0748/mana/blob/main/backend/src/index.ts): Express app · Composes domain routers and middleware · `backend/src/index.ts`
- [Auth Middleware](https://github.com/nico0748/mana/blob/main/backend/src/middleware/auth.ts): security boundary · Backend access-control gate · `backend/src/middleware/auth.ts`
- [Books Route](https://github.com/nico0748/mana/blob/main/backend/src/routes/books.ts): resource API · Book inventory and metadata endpoints · `backend/src/routes/books.ts`
- [Shopping Routes](https://github.com/nico0748/mana/blob/main/backend/src/routes/circles.ts): resource API · Circles, items, distributions, and events endpoints · `backend/src/routes/circles.ts`
- [Venue Maps](https://github.com/nico0748/mana/blob/main/backend/src/routes/venueMaps.ts): resource API · Venue map and navigation data endpoints · `backend/src/routes/venueMaps.ts`
- [Sync Route](https://github.com/nico0748/mana/blob/main/backend/src/routes/sync.ts): consistency API · Client state synchronization path · `backend/src/routes/sync.ts`
- [Prisma Client](https://github.com/nico0748/mana/blob/main/backend/src/prisma.ts): db client · Singleton database access layer · `backend/src/prisma.ts`

### Data

Database and schema assets

- [Prisma Schema](https://github.com/nico0748/mana/blob/main/backend/prisma/schema.prisma): schema · Source of truth for database shape and migrations · `backend/prisma/schema.prisma`
- **PostgreSQL**: database · Durable storage for app state

### Ops

Containerization and deployment

- [Compose Builds](https://github.com/nico0748/mana/blob/main/docker-compose.yml): deployment · Frontend/backend container packaging and startup · `docker-compose.yml`
- [GitHub Actions](https://github.com/nico0748/mana/blob/main/.github/workflows/deploy.yml): ci/cd · Automated deployment workflow · `.github/workflows/deploy.yml`

## Connections

- Browser → Nginx: loads app · Browser requests the PWA from the frontend origin
- Nginx → React App: serves SPA · Nginx serves the built frontend assets
- Nginx → API Entry: proxies /api · Same-origin API forwarding to backend
- React App → API Client: uses · UI code calls the typed API boundary
- React App → Auth State: shares session · App-wide auth state is provided through context
- React App → App Settings: shares prefs · App-wide settings are provided through context
- Books UI → API Client: reads/writes · Book screens use the typed REST client
- Shopping UI → API Client: reads/writes · Shopping list screens use the typed REST client
- Map UI → Route Logic: calculates · Map screens use pathfinding and navigation helpers
- Books UI → Book Enrichment: enriches · Book workflows consult external metadata services
- Auth State → Firebase Auth: signs in · Frontend authentication is delegated to Firebase
- API Entry → Auth Middleware: guards · API requests pass through auth enforcement
- API Entry → Books Route: mounts · Main API composition registers the books domain
- API Entry → Shopping Routes: mounts · Main API composition registers shopping-list domains
- API Entry → Venue Maps: mounts · Main API composition registers venue map routes
- API Entry → Sync Route: mounts · Main API composition registers sync routes
- Books Route → Prisma Client: persists · Books endpoints access the database through Prisma
- Shopping Routes → Prisma Client: persists · Shopping/event endpoints access the database through Prisma
- Venue Maps → Prisma Client: persists · Venue map endpoints access the database through Prisma
- Sync Route → Prisma Client: persists · Sync endpoints read and write through Prisma
- Prisma Client → Prisma Schema: uses schema · Client is backed by the Prisma schema and migrations
- Prisma Client → PostgreSQL: connects · Prisma talks to PostgreSQL as the durable store
- Compose Builds → Nginx: packages · Frontend container builds and serves the web app
- Compose Builds → API Entry: packages · Backend container builds and launches the API
- GitHub Actions → Compose Builds: deploys · Workflow drives build and release of containers
