# venkat-suresh-dev/world-odyssey architecture

> Architecture diagram of the GitHub repository venkat-suresh-dev/world-odyssey, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-31). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/venkat-suresh-dev/world-odyssey
- Repository: https://github.com/venkat-suresh-dev/world-odyssey

## Overview

#### Purpose and entry points
World Odyssey is a full-stack travel-learning platform: public country discovery/comparison plus authenticated travel tracking, quizzes, XP, levels, and achievements. Runtime entry points are the Express server at `backend/src/server.ts` / `backend/src/app.ts` and the Next.js App Router root at `frontend/src/app/layout.tsx` / `frontend/src/app/page.tsx`.

#### Frontend application shell
Next.js 16/React renders route-driven experiences for auth, exploration, country details, passport, quizzes, achievements, and comparison. Shared layout, theme, query caching, and auth state establish client-wide behavior. Primary paths: `frontend/src/app/explore/page.tsx`, `frontend/src/app/quiz/[mode]/page.tsx`, `frontend/src/components/providers/query-provider.tsx`, `frontend/src/store/useAuthStore.ts`.

#### Client-to-API boundary
Feature services encapsulate Axios calls to the versioned Express API; React Query hooks manage remote state and mutations. The auth store persists the JWT and the API client attaches it for protected operations. This boundary keeps pages/components independent from HTTP details. Paths: `frontend/src/services/api.ts`, `frontend/src/services/travel.ts`, `frontend/src/hooks/use-travel.ts`, `frontend/src/lib/auth-token.ts`.

#### API request pipeline and security
Express exposes domain route groups and applies route-layer JWT authentication, Zod validation, and centralized not-found/error handling. Controllers are HTTP adapters; services own rules and persistence. Core paths: `backend/src/routes/auth.routes.ts`, `backend/src/middlewares/auth.middleware.ts`, `backend/src/middlewares/validate.middleware.ts`, `backend/src/middlewares/errorHandler.middleware.ts`.

#### Domain services and progression
Services implement the central state transitions: authentication; country catalog queries; wishlist/visited mutations; quiz generation and server-side scoring; achievement evaluation. Travel and quiz completion award XP and drive derived level/progress plus achievement unlocks, so these flows are the main consistency boundary. Paths: `backend/src/services/travel.service.ts`, `backend/src/services/quiz.service.ts`, `backend/src/services/achievement.service.ts`, `backend/src/utils/xp.ts`.

#### Country data and geographic presentation
The backend periodically imports REST Countries data, maps it to the internal country model, and upserts PostgreSQL records. The browser uses shipped GeoJSON boundaries and Leaflet-compatible map presentation rather than relying on the API for geometry. Paths: `backend/src/services/countrySync.service.ts`, `backend/src/services/countrySync/mapRestCountryToUpsert.ts`, `frontend/public/data/countries.geojson`, `frontend/src/components/country-map.tsx`.

#### Persistence and infrastructure
Node.js/TypeScript runs Express with Prisma 7 over PostgreSQL 16+. The Prisma schema and migration history define the durable contract for users, countries, travel state, quiz attempts, and achievements. JWT/bcrypt secure sessions; REST Countries is an external synchronized source; OpenStreetMap/CARTO provide map tiles. Paths: `backend/prisma/schema.prisma`, `backend/prisma/migrations/20260728163858_add_travel_progression/migration.sql`, `backend/src/config/db.ts`, `backend/prisma.config.ts`.

Main entry points: [`frontend/src/app/page.tsx`](https://github.com/venkat-suresh-dev/world-odyssey/blob/main/frontend/src/app/page.tsx) (App routes), [`backend/src/app.ts`](https://github.com/venkat-suresh-dev/world-odyssey/blob/main/backend/src/app.ts) (Express application), [`backend/src/routes/auth.routes.ts`](https://github.com/venkat-suresh-dev/world-odyssey/blob/main/backend/src/routes/auth.routes.ts) (Domain routes), [`backend/src/services/travel.service.ts`](https://github.com/venkat-suresh-dev/world-odyssey/blob/main/backend/src/services/travel.service.ts) (Travel, quiz and achievements)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Next.js client"]
  node_next_routes["App routes<br/>Next.js App Router<br/>[page.tsx]"]
  node_client_providers["Client providers<br/>React state<br/>[query-provider.tsx]"]
  node_auth_store["Auth store<br/>JWT client state<br/>[useAuthStore.ts]"]
  node_feature_hooks["Travel query hooks<br/>React Query hooks<br/>[use-travel.ts]"]
  node_api_client["API client<br/>Axios services<br/>[api.ts]"]
  node_travel_service_client["Travel API service<br/>feature service<br/>[travel.ts]"]
  node_country_map["Country map<br/>Leaflet presentation<br/>[country-map.tsx]"]
  node_geojson["Country boundaries<br/>GeoJSON asset<br/>[countries.geojson]"]
end

subgraph group_api["Express API"]
  node_express_app["Express application<br/>Node.js runtime<br/>[app.ts]"]
  node_api_routes["Domain routes<br/>Express routes<br/>[auth.routes.ts]"]
  node_request_security["Auth and validation<br/>route middleware<br/>[auth.middleware.ts]"]
  node_error_handling["Error handling<br/>Express middleware"]
  node_domain_services["Travel, quiz and achievements<br/>domain services<br/>[travel.service.ts]"]
  node_progression["XP and level rules<br/>progression logic<br/>[xp.ts]"]
  node_country_sync["Country synchronization<br/>import service"]
end

subgraph group_data["Data and infrastructure"]
  node_prisma["Prisma data model<br/>ORM schema<br/>[schema.prisma]"]
  node_postgres[("PostgreSQL<br/>database<br/>[db.ts]")]
  node_rest_countries{{"REST Countries<br/>external data source"}}
  node_map_tiles{{"OSM and CARTO tiles<br/>map tile providers"}}
end

node_next_routes -->|"runs within"| node_client_providers
node_next_routes -->|"uses"| node_feature_hooks
node_next_routes -->|"reads session"| node_auth_store
node_feature_hooks -->|"calls"| node_travel_service_client
node_travel_service_client -->|"uses"| node_api_client
node_auth_store -->|"supplies JWT"| node_api_client
node_api_client -->|"HTTPS API requests"| node_express_app
node_country_map -->|"loads boundaries"| node_geojson
node_country_map -->|"renders tiles"| node_map_tiles
node_express_app -->|"mounts"| node_api_routes
node_express_app -->|"centralizes failures"| node_error_handling
node_api_routes -->|"applies"| node_request_security
node_api_routes -->|"dispatches to"| node_domain_services
node_domain_services -->|"awards XP for travel and quizzes"| node_progression
node_domain_services -->|"persists state"| node_prisma
node_country_sync -->|"imports catalog"| node_rest_countries
node_country_sync -->|"upserts countries"| node_prisma
node_prisma -->|"reads and writes"| node_postgres

click node_next_routes "https://github.com/venkat-suresh-dev/world-odyssey/blob/main/frontend/src/app/page.tsx"
click node_client_providers "https://github.com/venkat-suresh-dev/world-odyssey/blob/main/frontend/src/components/providers/query-provider.tsx"
click node_auth_store "https://github.com/venkat-suresh-dev/world-odyssey/blob/main/frontend/src/store/useAuthStore.ts"
click node_feature_hooks "https://github.com/venkat-suresh-dev/world-odyssey/blob/main/frontend/src/hooks/use-travel.ts"
click node_api_client "https://github.com/venkat-suresh-dev/world-odyssey/blob/main/frontend/src/services/api.ts"
click node_travel_service_client "https://github.com/venkat-suresh-dev/world-odyssey/blob/main/frontend/src/services/travel.ts"
click node_country_map "https://github.com/venkat-suresh-dev/world-odyssey/blob/main/frontend/src/components/country-map.tsx"
click node_geojson "https://github.com/venkat-suresh-dev/world-odyssey/blob/main/frontend/public/data/countries.geojson"
click node_express_app "https://github.com/venkat-suresh-dev/world-odyssey/blob/main/backend/src/app.ts"
click node_api_routes "https://github.com/venkat-suresh-dev/world-odyssey/blob/main/backend/src/routes/auth.routes.ts"
click node_request_security "https://github.com/venkat-suresh-dev/world-odyssey/blob/main/backend/src/middlewares/auth.middleware.ts"
click node_error_handling "https://github.com/venkat-suresh-dev/world-odyssey/blob/main/backend/src/middlewares/errorHandler.middleware.ts"
click node_domain_services "https://github.com/venkat-suresh-dev/world-odyssey/blob/main/backend/src/services/travel.service.ts"
click node_progression "https://github.com/venkat-suresh-dev/world-odyssey/blob/main/backend/src/utils/xp.ts"
click node_country_sync "https://github.com/venkat-suresh-dev/world-odyssey/blob/main/backend/src/services/countrySync.service.ts"
click node_prisma "https://github.com/venkat-suresh-dev/world-odyssey/blob/main/backend/prisma/schema.prisma"
click node_postgres "https://github.com/venkat-suresh-dev/world-odyssey/blob/main/backend/src/config/db.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_next_routes,node_client_providers,node_auth_store,node_feature_hooks,node_api_client,node_travel_service_client,node_country_map,node_geojson toneBlue
class node_express_app,node_api_routes,node_request_security,node_error_handling,node_domain_services,node_progression,node_country_sync toneAmber
class node_prisma,node_postgres,node_rest_countries,node_map_tiles toneMint
```

## Components

### Next.js client

- [App routes](https://github.com/venkat-suresh-dev/world-odyssey/blob/main/frontend/src/app/page.tsx): Next.js App Router · Public discovery, auth, passport, quiz, achievement, and comparison experiences. · `frontend/src/app/page.tsx`
- [Client providers](https://github.com/venkat-suresh-dev/world-odyssey/blob/main/frontend/src/components/providers/query-provider.tsx): React state · Theme, query cache, and shared client behavior. · `frontend/src/components/providers/query-provider.tsx`
- [Auth store](https://github.com/venkat-suresh-dev/world-odyssey/blob/main/frontend/src/store/useAuthStore.ts): JWT client state · Persists authenticated client state. · `frontend/src/store/useAuthStore.ts`
- [Travel query hooks](https://github.com/venkat-suresh-dev/world-odyssey/blob/main/frontend/src/hooks/use-travel.ts): React Query hooks · Remote travel state and mutations for UI features. · `frontend/src/hooks/use-travel.ts`
- [API client](https://github.com/venkat-suresh-dev/world-odyssey/blob/main/frontend/src/services/api.ts): Axios services · Attaches JWTs and isolates versioned API calls. · `frontend/src/services/api.ts`
- [Travel API service](https://github.com/venkat-suresh-dev/world-odyssey/blob/main/frontend/src/services/travel.ts): feature service · `frontend/src/services/travel.ts`
- [Country map](https://github.com/venkat-suresh-dev/world-odyssey/blob/main/frontend/src/components/country-map.tsx): Leaflet presentation · Renders country geography in the browser. · `frontend/src/components/country-map.tsx`
- [Country boundaries](https://github.com/venkat-suresh-dev/world-odyssey/blob/main/frontend/public/data/countries.geojson): GeoJSON asset · Shipped browser-side geometry. · `frontend/public/data/countries.geojson`

### Express API

- [Express application](https://github.com/venkat-suresh-dev/world-odyssey/blob/main/backend/src/app.ts): Node.js runtime · Versioned API entry point and middleware host. · `backend/src/app.ts`
- [Domain routes](https://github.com/venkat-suresh-dev/world-odyssey/blob/main/backend/src/routes/auth.routes.ts): Express routes · Route groups dispatch authenticated API requests. · `backend/src/routes/auth.routes.ts`
- [Auth and validation](https://github.com/venkat-suresh-dev/world-odyssey/blob/main/backend/src/middlewares/auth.middleware.ts): route middleware · JWT protection and Zod request validation. · `backend/src/middlewares/auth.middleware.ts`
- [Error handling](https://github.com/venkat-suresh-dev/world-odyssey/blob/main/backend/src/middlewares/errorHandler.middleware.ts): Express middleware · Centralized not-found and error responses. · `backend/src/middlewares/errorHandler.middleware.ts`
- [Travel, quiz and achievements](https://github.com/venkat-suresh-dev/world-odyssey/blob/main/backend/src/services/travel.service.ts): domain services · Owns travel mutations, quiz scoring, and achievement evaluation. · `backend/src/services/travel.service.ts`
- [XP and level rules](https://github.com/venkat-suresh-dev/world-odyssey/blob/main/backend/src/utils/xp.ts): progression logic · Awards XP and derives levels and progress from completed actions. · `backend/src/utils/xp.ts`
- [Country synchronization](https://github.com/venkat-suresh-dev/world-odyssey/blob/main/backend/src/services/countrySync.service.ts): import service · Maps and upserts the external country catalog. · `backend/src/services/countrySync.service.ts`

### Data and infrastructure

- [Prisma data model](https://github.com/venkat-suresh-dev/world-odyssey/blob/main/backend/prisma/schema.prisma): ORM schema · Durable model for users, countries, travel, quiz attempts, and achievements. · `backend/prisma/schema.prisma`
- [PostgreSQL](https://github.com/venkat-suresh-dev/world-odyssey/blob/main/backend/src/config/db.ts): database · `backend/src/config/db.ts`
- **REST Countries**: external data source
- **OSM and CARTO tiles**: map tile providers

## Connections

- App routes → Client providers: runs within
- App routes → Travel query hooks: uses
- App routes → Auth store: reads session
- Travel query hooks → Travel API service: calls
- Travel API service → API client: uses
- Auth store → API client: supplies JWT
- API client → Express application: HTTPS API requests
- Country map → Country boundaries: loads boundaries
- Country map → OSM and CARTO tiles: renders tiles
- Express application → Domain routes: mounts
- Express application → Error handling: centralizes failures
- Domain routes → Auth and validation: applies
- Domain routes → Travel, quiz and achievements: dispatches to
- Travel, quiz and achievements → XP and level rules: awards XP for travel and quizzes
- Travel, quiz and achievements → Prisma data model: persists state
- Country synchronization → REST Countries: imports catalog
- Country synchronization → Prisma data model: upserts countries
- Prisma data model → PostgreSQL: reads and writes