How nico0748/mana works
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: index.ts API Entry · prisma.ts Prisma Client · App.tsx React App · nginx.conf Nginx
Components 23
Runtime
Production request path and service boundaries
- Browser · End-user PWA entrypoint
- Nginx · Serves SPA and reverse-proxies API requests
frontend/nginx.conf - Firebase Auth · Sign-in provider for email/password and Google login
frontend/src/lib/firebase.ts
Frontend
React/Vite PWA and browser-side logic
- React App · Main frontend application shell
frontend/src/App.tsx - API Client · Typed boundary for browser-to-server calls
frontend/src/lib/api.ts - Auth State · Session and login state management
frontend/src/contexts/AuthContext.tsx - App Settings · Global app preferences and shared settings
frontend/src/contexts/AppSettingsContext.tsx - Books UI · Barcode scan, edit, list, and detail views
frontend/src/components/books/BookList.tsx - Shopping UI · Event, circle, and list assembly screens
frontend/src/pages/ShoppingListPage.tsx - Map UI · Venue schematic maps and navigation pages
frontend/src/pages/MapPage.tsx - Route Logic · Venue route calculation and navigation helpers
frontend/src/lib/dijkstra.ts - Book Enrichment · ISBN metadata lookup via OpenBD and Google Books
frontend/src/lib/bookApi.ts
Backend
Express API and persistence
- API Entry · Composes domain routers and middleware
backend/src/index.ts - Auth Middleware · Backend access-control gate
backend/src/middleware/auth.ts - Books Route · Book inventory and metadata endpoints
backend/src/routes/books.ts - Shopping Routes · Circles, items, distributions, and events endpoints
backend/src/routes/circles.ts - Venue Maps · Venue map and navigation data endpoints
backend/src/routes/venueMaps.ts - Sync Route · Client state synchronization path
backend/src/routes/sync.ts - Prisma Client · Singleton database access layer
backend/src/prisma.ts
Data
Database and schema assets
- Prisma Schema · Source of truth for database shape and migrations
backend/prisma/schema.prisma - PostgreSQL · Durable storage for app state
Ops
Containerization and deployment
- Compose Builds · Frontend/backend container packaging and startup
docker-compose.yml - GitHub Actions · Automated deployment workflow
.github/workflows/deploy.yml
Connections 25
- 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