How mhmdsami/globetrotter works
<explanation>
1. Identify the project type and purpose
- This is a full‑stack web application called “globetrotter”—a trivia game where users sign up, answer location challenges, and see fun facts.
- The repo splits into two clearly delineated parts:
• server/ – a Hono‑based REST API in TypeScript with Prisma (ODM) backed by MongoDB
• www/ – a Next.js 13 (App Router) React frontend with built‑in API routes
2. Analyze the file structure
Top level:
• server/
– prisma/schema.prisma → DB schema
– src/index.ts → Hono app entrypoint
– src/routes/{user,challenge,game}.ts → REST endpoints
– src/middlewares → auth & validation
– src/utils → config, db client, seed data loader, transformers
– .env.example → DATABASE_URL, JWT secrets
• www/
– next.config.ts, .env.example → FRONTEND_API_URL, etc.
– src/app → App‑Router pages, layouts, auth vs main sections
– src/app/api/generate‑challenge‑card/route.ts → edge function for card generation
– src/api/*.ts → client wrappers for calling server REST API
– src/components, src/contexts, src/utils → UI building blocks, global styles, context providers
3. Key insights from README
- Frontend: React + Next.js + TailwindCSS
- Backend: Hono (lightweight, type-safe), Prisma (ODM), MongoDB
- Two processes: npm run dev in server/ and www/
- API documented in Postman
4. How to create the system design diagram
a. Main components
1. Client Browser (React UI in Next.js)
2. Next.js App Server (SSR/SSG + App‑Router + built‑in API routes)
3. Hono API Server (REST endpoints: /user, /challenge, /game)
4. MongoDB Database (hosted via connection string)
5. Prisma ORM/ODM (data access layer inside server)
6. External Card Generation Service (e.g., AI/Image API used by generate-challenge-card route)
b. Relationships & data flows
- User Browser ↔ Next.js Frontend pages (SSR, client-side routing, React components)
- Browser → Next.js Built‑in API (e.g., /api/generate‑challenge‑card) → External Service → Next.js → Browser
- Browser → Next.js client‑side fetch (src/api/*.ts) → Hono API Server → Prisma → MongoDB → Prisma → Hono → Browser
- Authentication: Browser stores JWT, which Next.js API wrappers include in Authorization headers to Hono API
- Optional: Seeding & migrations via Prisma CLI (dev tooling, not in runtime diagram)
c. Architectural patterns & principles
- Separation of concerns: UI layer (Next.js) vs business logic & data layer (Hono + Prisma)
- RESTful API design (resources: user, challenge, game)
- Middleware pipeline: authentication, validation
- Serverless edge function for on‑the‑fly card generation
- Type safety across stack (TypeScript everywhere)
d. Key technologies
- React & Next.js App Router (frontend SSR/CSR)
- TailwindCSS (styling)
- Hono (lightweight Node HTTP framework)
- Prisma (ODM for MongoDB)
- MongoDB (NoSQL document store)
- External AI/image API (for dynamic challenge cards)
5. Tailoring the diagram for a full‑stack application
- Use distinct swimlanes or colored boxes for “Frontend” vs “Backend” vs “Database” vs “External Services”
- Emphasize the flow from user interactions in React → Next.js UI → API calls → persistence
- Show Next.js both as a UI server and as a host for lightweight API routes
- Highlight authentication flow and middleware
6. Diagram guidelines
- Label every component clearly (e.g., Next.js App Server, Hono API, MongoDB)
- Use directional arrows for request/response paths
- Color‑code:
• Blue for UI (React/Next.js)
• Green for backend services (Hono, Prisma)
• Orange for database (MongoDB)
• Purple for external services (AI/Image API)
- Use distinct shapes: rectangles for services, cylinders for databases, clouds for third‑party APIs
7. Final advice
- Drill into each piece of the file tree: each middleware, route group, and utility maps to a box or subcomponent in your diagram
- Capture both runtime flows (HTTP requests) and build/dev tooling (Prisma migrations, seed scripts) if relevant to your audience
- Keep the diagram uncluttered by grouping related files (e.g., all src/routes under “Hono API”) but annotate patterns (auth, validation, ORM) clearly
- Don’t overthink—maximally decompose into logical layers and services to give a comprehensive yet readable overview
</explanation>