How venkat-suresh-dev/world-odyssey works
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: page.tsx App routes · app.ts Express application · auth.routes.ts Domain routes · travel.service.ts Travel, quiz and achievements
Components 19
Next.js client
- App routes · Public discovery, auth, passport, quiz, achievement, and comparison experiences.
frontend/src/app/page.tsx - Client providers · Theme, query cache, and shared client behavior.
frontend/src/components/providers/query-provider.tsx - Auth store · Persists authenticated client state.
frontend/src/store/useAuthStore.ts - Travel query hooks · Remote travel state and mutations for UI features.
frontend/src/hooks/use-travel.ts - API client · Attaches JWTs and isolates versioned API calls.
frontend/src/services/api.ts - Travel API service
frontend/src/services/travel.ts - Country map · Renders country geography in the browser.
frontend/src/components/country-map.tsx - Country boundaries · Shipped browser-side geometry.
frontend/public/data/countries.geojson
Express API
- Express application · Versioned API entry point and middleware host.
backend/src/app.ts - Domain routes · Route groups dispatch authenticated API requests.
backend/src/routes/auth.routes.ts - Auth and validation · JWT protection and Zod request validation.
backend/src/middlewares/auth.middleware.ts - Error handling · Centralized not-found and error responses.
backend/src/middlewares/errorHandler.middleware.ts - Travel, quiz and achievements · Owns travel mutations, quiz scoring, and achievement evaluation.
backend/src/services/travel.service.ts - XP and level rules · Awards XP and derives levels and progress from completed actions.
backend/src/utils/xp.ts - Country synchronization · Maps and upserts the external country catalog.
backend/src/services/countrySync.service.ts
Data and infrastructure
- Prisma data model · Durable model for users, countries, travel, quiz attempts, and achievements.
backend/prisma/schema.prisma - PostgreSQL
backend/src/config/db.ts - REST Countries
- OSM and CARTO tiles
Connections 18
- 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