# ngtruongmetin/viviora architecture

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

- Interactive diagram: https://gitdiagram.com/ngtruongmetin/viviora
- Repository: https://github.com/ngtruongmetin/viviora

## Overview

Viviora is a social reading platform for middle-school students, with staff administration. The main journey is a signed-in reader discovering books and community posts, recording reading activity, and progressing through achievements, missions, and book-linked games; staff moderate content and manage platform resources. The React SPA routes users to these experiences, while Express exposes session-authenticated REST endpoints backed by PostgreSQL. The graph preserves documented AI advising, surveys, and question banks as distinct capabilities. Some routes and page implementations were not sampled, so their internal connections are omitted rather than inferred.

Main entry points: [`backend/app.js`](https://github.com/ngtruongmetin/viviora/blob/main/backend/app.js) (Express API composition), [`backend/database/db.js`](https://github.com/ngtruongmetin/viviora/blob/main/backend/database/db.js) (PostgreSQL pool), [`backend/services/achievementService.js`](https://github.com/ngtruongmetin/viviora/blob/main/backend/services/achievementService.js) (Achievement service), [`frontend/src/App.tsx`](https://github.com/ngtruongmetin/viviora/blob/main/frontend/src/App.tsx) (React application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_spa["React application<br/>[App.tsx]"]
  node_routing["Page routing<br/>[AppRoutes.tsx]"]
end

subgraph group_identity["Identity and access"]
  node_authui["Session context<br/>[AuthContext.tsx]"]
  node_authroutes["Authentication API<br/>[auth.js]"]
  node_guards["Role guards<br/>[auth.js]"]
end

subgraph group_community["Community and progression"]
  node_feedpage["Community pages<br/>[FeedPage.tsx]"]
  node_communityroutes["Posts and feed API<br/>[posts.js]"]
  node_moderation["Moderation API<br/>[moderation.js]"]
  node_profile["Profile and activity<br/>[profile.js]"]
  node_achievements["Achievement service"]
  node_missions["Weekly missions<br/>[weeklyMissions.js]"]
end

subgraph group_reading["Reading and learning"]
  node_libraryui["Library pages<br/>[LibraryPage.tsx]"]
  node_libraryroutes["Library API<br/>[library.js]"]
  node_libraryservice["Catalog service<br/>[libraryService.js]"]
  node_ai["AI book advisor<br/>[aiService.js]"]
  node_questionbanks["Question banks<br/>[questionBanks.js]"]
  node_games["Game sessions<br/>[gameService.js]"]
  node_surveys["Survey service<br/>[surveyService.js]"]
end

subgraph group_platform["API and persistence"]
  node_api["Express API composition<br/>[app.js]"]
  node_database[("PostgreSQL pool<br/>[db.js]")]
  node_sessions["Session store<br/>[sessionStore.js]"]
end

node_reader(("Reader or staff"))

node_reader -.->|"uses"| node_spa
node_spa -->|"provides context"| node_authui
node_spa -->|"renders routes"| node_routing
node_routing -->|"routes to"| node_feedpage
node_authui -.->|"requests session"| node_authroutes
node_api -->|"mounts"| node_authroutes
node_api -->|"mounts"| node_communityroutes
node_api -->|"mounts"| node_moderation
node_api -->|"mounts"| node_profile
node_api -->|"mounts"| node_libraryroutes
node_api -->|"mounts"| node_questionbanks
node_api -->|"mounts"| node_games
node_api -->|"mounts"| node_missions
node_api -->|"mounts"| node_surveys
node_api -->|"mounts route"| node_ai
node_communityroutes -->|"evaluates"| node_achievements
node_profile -->|"evaluates"| node_achievements
node_authroutes -->|"evaluates"| node_achievements
node_libraryroutes -->|"calls"| node_libraryservice
node_libraryroutes -->|"evaluates"| node_achievements
node_games -->|"evaluates"| node_achievements
node_communityroutes -->|"queries"| node_database
node_profile -->|"queries"| node_database
node_libraryservice -->|"queries"| node_database
node_achievements -->|"queries"| node_database
node_games -->|"queries"| node_database
node_ai -->|"queries"| node_database
node_surveys -->|"queries"| node_database
node_api -->|"configures store"| node_sessions
node_sessions -->|"uses pool"| node_database
node_guards -->|"checks account"| node_database

click node_spa "https://github.com/ngtruongmetin/viviora/blob/main/frontend/src/App.tsx"
click node_routing "https://github.com/ngtruongmetin/viviora/blob/main/frontend/src/routes/AppRoutes.tsx"
click node_authui "https://github.com/ngtruongmetin/viviora/blob/main/frontend/src/auth/AuthContext.tsx"
click node_authroutes "https://github.com/ngtruongmetin/viviora/blob/main/backend/routes/auth.js"
click node_guards "https://github.com/ngtruongmetin/viviora/blob/main/backend/middlewares/auth.js"
click node_feedpage "https://github.com/ngtruongmetin/viviora/blob/main/frontend/src/pages/community/FeedPage.tsx"
click node_communityroutes "https://github.com/ngtruongmetin/viviora/blob/main/backend/routes/posts.js"
click node_moderation "https://github.com/ngtruongmetin/viviora/blob/main/backend/routes/moderation.js"
click node_profile "https://github.com/ngtruongmetin/viviora/blob/main/backend/routes/profile.js"
click node_achievements "https://github.com/ngtruongmetin/viviora/blob/main/backend/services/achievementService.js"
click node_missions "https://github.com/ngtruongmetin/viviora/blob/main/backend/routes/weeklyMissions.js"
click node_libraryui "https://github.com/ngtruongmetin/viviora/blob/main/frontend/src/pages/library/LibraryPage.tsx"
click node_libraryroutes "https://github.com/ngtruongmetin/viviora/blob/main/backend/routes/library.js"
click node_libraryservice "https://github.com/ngtruongmetin/viviora/blob/main/backend/services/libraryService.js"
click node_ai "https://github.com/ngtruongmetin/viviora/blob/main/backend/services/aiService.js"
click node_questionbanks "https://github.com/ngtruongmetin/viviora/blob/main/backend/routes/questionBanks.js"
click node_games "https://github.com/ngtruongmetin/viviora/blob/main/backend/services/gameService.js"
click node_surveys "https://github.com/ngtruongmetin/viviora/blob/main/backend/services/surveyService.js"
click node_api "https://github.com/ngtruongmetin/viviora/blob/main/backend/app.js"
click node_database "https://github.com/ngtruongmetin/viviora/blob/main/backend/database/db.js"
click node_sessions "https://github.com/ngtruongmetin/viviora/blob/main/backend/sessionStore.js"

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_spa,node_routing toneBlue
class node_authui,node_authroutes,node_guards toneAmber
class node_feedpage,node_communityroutes,node_moderation,node_profile,node_achievements,node_missions toneMint
class node_libraryui,node_libraryroutes,node_libraryservice,node_ai,node_questionbanks,node_games,node_surveys toneRose
class node_api,node_database,node_sessions,node_reader toneIndigo
```

## Components

### Web experience

- [React application](https://github.com/ngtruongmetin/viviora/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Page routing](https://github.com/ngtruongmetin/viviora/blob/main/frontend/src/routes/AppRoutes.tsx): `frontend/src/routes/AppRoutes.tsx`

### Identity and access

- [Session context](https://github.com/ngtruongmetin/viviora/blob/main/frontend/src/auth/AuthContext.tsx): `frontend/src/auth/AuthContext.tsx`
- [Authentication API](https://github.com/ngtruongmetin/viviora/blob/main/backend/routes/auth.js): `backend/routes/auth.js`
- [Role guards](https://github.com/ngtruongmetin/viviora/blob/main/backend/middlewares/auth.js): `backend/middlewares/auth.js`

### Community and progression

- [Community pages](https://github.com/ngtruongmetin/viviora/blob/main/frontend/src/pages/community/FeedPage.tsx): `frontend/src/pages/community/FeedPage.tsx`
- [Posts and feed API](https://github.com/ngtruongmetin/viviora/blob/main/backend/routes/posts.js): `backend/routes/posts.js`
- [Moderation API](https://github.com/ngtruongmetin/viviora/blob/main/backend/routes/moderation.js): `backend/routes/moderation.js`
- [Profile and activity](https://github.com/ngtruongmetin/viviora/blob/main/backend/routes/profile.js): `backend/routes/profile.js`
- [Achievement service](https://github.com/ngtruongmetin/viviora/blob/main/backend/services/achievementService.js): `backend/services/achievementService.js`
- [Weekly missions](https://github.com/ngtruongmetin/viviora/blob/main/backend/routes/weeklyMissions.js): `backend/routes/weeklyMissions.js`

### Reading and learning

- [Library pages](https://github.com/ngtruongmetin/viviora/blob/main/frontend/src/pages/library/LibraryPage.tsx): `frontend/src/pages/library/LibraryPage.tsx`
- [Library API](https://github.com/ngtruongmetin/viviora/blob/main/backend/routes/library.js): `backend/routes/library.js`
- [Catalog service](https://github.com/ngtruongmetin/viviora/blob/main/backend/services/libraryService.js): `backend/services/libraryService.js`
- [AI book advisor](https://github.com/ngtruongmetin/viviora/blob/main/backend/services/aiService.js): `backend/services/aiService.js`
- [Question banks](https://github.com/ngtruongmetin/viviora/blob/main/backend/routes/questionBanks.js): `backend/routes/questionBanks.js`
- [Game sessions](https://github.com/ngtruongmetin/viviora/blob/main/backend/services/gameService.js): `backend/services/gameService.js`
- [Survey service](https://github.com/ngtruongmetin/viviora/blob/main/backend/services/surveyService.js): `backend/services/surveyService.js`

### API and persistence

- [Express API composition](https://github.com/ngtruongmetin/viviora/blob/main/backend/app.js): `backend/app.js`
- [PostgreSQL pool](https://github.com/ngtruongmetin/viviora/blob/main/backend/database/db.js): `backend/database/db.js`
- [Session store](https://github.com/ngtruongmetin/viviora/blob/main/backend/sessionStore.js): `backend/sessionStore.js`

### Other components

- **Reader or staff**

## Connections

- Reader or staff → React application: uses
- React application → Session context: provides context (evidence: `frontend/src/App.tsx`)
- React application → Page routing: renders routes (evidence: `frontend/src/App.tsx`)
- Page routing → Community pages: routes to (evidence: `frontend/src/routes/AppRoutes.tsx`)
- Session context → Authentication API: requests session
- Express API composition → Authentication API: mounts (evidence: `backend/app.js`)
- Express API composition → Posts and feed API: mounts (evidence: `backend/app.js`)
- Express API composition → Moderation API: mounts (evidence: `backend/app.js`)
- Express API composition → Profile and activity: mounts (evidence: `backend/app.js`)
- Express API composition → Library API: mounts (evidence: `backend/app.js`)
- Express API composition → Question banks: mounts (evidence: `backend/app.js`)
- Express API composition → Game sessions: mounts (evidence: `backend/app.js`)
- Express API composition → Weekly missions: mounts (evidence: `backend/app.js`)
- Express API composition → Survey service: mounts (evidence: `backend/app.js`)
- Express API composition → AI book advisor: mounts route (evidence: `backend/app.js`)
- Posts and feed API → Achievement service: evaluates (evidence: `backend/routes/posts.js`)
- Profile and activity → Achievement service: evaluates (evidence: `backend/routes/profile.js`)
- Authentication API → Achievement service: evaluates (evidence: `backend/routes/auth.js`)
- Library API → Catalog service: calls (evidence: `backend/routes/library.js`)
- Library API → Achievement service: evaluates (evidence: `backend/routes/library.js`)
- Game sessions → Achievement service: evaluates (evidence: `backend/services/gameService.js`)
- Posts and feed API → PostgreSQL pool: queries (evidence: `backend/routes/posts.js`)
- Profile and activity → PostgreSQL pool: queries (evidence: `backend/routes/profile.js`)
- Catalog service → PostgreSQL pool: queries (evidence: `backend/services/libraryService.js`)
- Achievement service → PostgreSQL pool: queries (evidence: `backend/services/achievementService.js`)
- Game sessions → PostgreSQL pool: queries (evidence: `backend/services/gameService.js`)
- AI book advisor → PostgreSQL pool: queries (evidence: `backend/services/aiService.js`)
- Survey service → PostgreSQL pool: queries (evidence: `backend/services/surveyService.js`)
- Express API composition → Session store: configures store (evidence: `backend/app.js`)
- Session store → PostgreSQL pool: uses pool (evidence: `backend/sessionStore.js`)
- Role guards → PostgreSQL pool: checks account (evidence: `backend/middlewares/auth.js`)
