How apun16/6-degrees works
1. Overall shape
- This is a two-tier application: a Next.js frontend presents the word game UI, and a Flask backend owns semantic-word logic, scoring, and validation.
- The main architectural boundary is HTTP API calls from the frontend to the backend; the game logic is not embedded in the browser.
2. Frontend responsibility
- The frontend is a Next.js app with a single-page game experience built from Landing, Game, WordInput, WordChain, Results, and HowToPlay.
- page.tsx and layout.tsx define the app shell; the gameplay components handle state, rendering, and user interaction.
- Styling is done with CSS Modules and global CSS.
3. Frontend data flow
- User input begins in WordInput, flows into Game, and is reflected in WordChain and Results.
- The frontend uses src/utils/api.js as the network boundary for all gameplay requests: validate words, request hints, submit paths, fetch the optimal path, and calculate score.
- The frontend appears to keep the interactive game state locally while using the backend for authoritative semantic checks.
4. Backend service layout
- The Flask backend is split into a small set of clear services:
- routes.py for REST endpoints
- game_service.py for orchestration and game rules
- semantic_graph.py for graph and pathfinding logic
- embedding_service.py for vector generation and similarity
- word_database.py for valid-word lookup and word inventory
- run.py is the application entry point; Procfile and Dockerfile show it is deployed as a containerized web service.
5. Core semantic model
- The game is built on an implicit semantic graph rather than a manually curated link table.
- embedding_service.py generates 384-dimensional sentence embeddings using Hugging Face all-MiniLM-L6-v2.
- semantic_graph.py connects words when cosine similarity exceeds the configured threshold, creating edges dynamically as words are added.
6. Pathfinding and validation
- The backend computes the optimal path between words with breadth-first search over the semantic graph.
- Game validation checks that a candidate word is real, not duplicated in the current chain, and semantically close enough to the previous word.
- This makes the backend the source of truth for whether a move is legal and whether a submitted chain is complete.
7. Game orchestration
- game_service.py sits above the embedding/graph/database layers and coordinates puzzle generation, path validation, scoring, and hint generation.
- The README’s API list suggests the game lifecycle is: start a puzzle, extend the chain, request hints if needed, submit the result, then compare against the optimal path.
- Scoring is based on the player’s path length relative to the algorithmic solution.
8. Word inventory and startup behavior
- word_database.py manages the valid word set used by the game.
- The backend is optimized for startup by preloading common words and pre-initializing services, which matters because semantic embeddings and graph construction are relatively expensive.
- The architecture is biased toward fast reads during gameplay, with heavier model work moved to startup or cached.
9. Persistence and external services
- The README indicates Supabase/PostgreSQL is part of the infrastructure, and the frontend includes utils/supabase.js, suggesting some app data or stats integration outside the core gameplay loop.
- The public gameplay loop itself is still primarily API-driven; the semantic graph and scoring logic live in the backend rather than in the database.
- Vercel hosts the frontend, while Railway runs the backend container.
10. Testing and CI boundaries
- The repo is split cleanly into frontend Jest tests and backend pytest tests.
- GitHub Actions has separate workflows for frontend and backend, which reinforces the architectural separation of concerns.
- Backend tests cover embeddings, graph behavior, services, and routes; frontend tests cover game state, API integration, input validation, and score rendering.
11. Deployment topology
- Frontend deploys as a static/Next.js app on Vercel, with the backend URL injected via environment variable.
- Backend deploys as a Dockerized Flask/Gunicorn service on Railway.
- This is a classic split deployment: browser UI on a CDN-backed frontend, compute-heavy semantic logic on a separate API service.
12. What to show in an architecture diagram
- The central flow should be: player browser → Next.js UI → Flask API → semantic graph / embeddings / word lookup → response back to UI.
- Around that, show supporting boundaries for Supabase, GitHub Actions CI, and the two deployment targets (Vercel and Railway).
- The most important internal backend dependency chain is: routes → game service → semantic graph / embedding service / word database.
Main entry points: Game.jsx Game · game_service.py Game Service · page.tsx App Shell · routes.py Routes
Components 19
Frontend
Next.js UI, client state, and browser-side API boundary
- App Shell · Page and layout entry points
frontend/src/app/page.tsx - Game · Main gameplay controller and state holder
frontend/src/components/Game.jsx - Word Input · Captures player guesses
frontend/src/components/WordInput.jsx - Word Chain · Renders the current chain
frontend/src/components/WordChain.jsx - Results · Shows completion and score
frontend/src/components/Results.jsx - How To Play · Explains the game rules
frontend/src/components/HowToPlay.jsx - API Client · All gameplay requests to the backend
frontend/src/utils/api.js - Supabase · Non-core app data or stats integration
frontend/src/utils/supabase.js
Backend
Flask service and semantic game logic
- Routes · HTTP endpoints for gameplay actions
backend/app/routes.py - Game Service · Coordinates rules, hints, scoring, and puzzle flow
backend/app/game_service.py - Semantic Graph · Builds and traverses word similarity links
backend/app/semantic_graph.py - Embeddings · Generates sentence embeddings and similarity inputs
backend/app/embedding_service.py - Word DB · Valid-word lookup and preload set
backend/app/word_database.py - Run App · Starts the Flask application
backend/run.py
Infra
External services, CI, and deployment targets
- CI Workflows · Separate frontend and backend test pipelines
.github/workflows/test-backend.yml - Vercel · Hosts the Next.js frontend
- Railway · Runs the containerized Flask backend
- Supabase · External data layer used by the app
Other components
- Player · User playing the word game
Connections 21
- Player → App Shell: uses · Player interacts with the web UI
- App Shell → Game: renders · App shell hosts the game experience
- Game → Word Input: captures · User input enters the game flow
- Game → Word Chain: updates · Current chain is reflected in the UI
- Game → Results: shows · Completion and scoring view
- Game → How To Play: explains · Help content is available from the game
- Game → API Client: calls · Game state triggers backend requests
- API Client → Routes: HTTP · Frontend requests hit Flask endpoints
- Routes → Game Service: orchestrates · Routes delegate gameplay work
- Game Service → Semantic Graph: queries · Uses graph logic for validation and pathing
- Game Service → Embeddings: builds · Embeddings feed semantic similarity
- Game Service → Word DB: checks · Validates words against the inventory
- Semantic Graph → Embeddings: depends on · Similarity edges derive from vectors
- Semantic Graph → Word DB: expands from · Graph grows from available words
- Run App → Routes: boots · Application entry loads the API
- CI Workflows → App Shell: tests · Frontend workflow covers the UI
- CI Workflows → Routes: tests · Backend workflow covers service and API
- App Shell → Vercel: deploys to · Frontend is hosted on Vercel
- Run App → Railway: deploys to · Backend runs on Railway
- API Client → Supabase: optional data · Frontend may use Supabase for app data
- Supabase → Supabase: connects · Client integration reaches the external datastore