# apun16/6-degrees architecture

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

- Interactive diagram: https://gitdiagram.com/apun16/6-degrees
- Repository: https://github.com/apun16/6-degrees

## Overview

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: [`frontend/src/components/Game.jsx`](https://github.com/apun16/6-degrees/blob/main/frontend/src/components/Game.jsx) (Game), [`backend/app/game_service.py`](https://github.com/apun16/6-degrees/blob/main/backend/app/game_service.py) (Game Service), [`frontend/src/app/page.tsx`](https://github.com/apun16/6-degrees/blob/main/frontend/src/app/page.tsx) (App Shell), [`backend/app/routes.py`](https://github.com/apun16/6-degrees/blob/main/backend/app/routes.py) (Routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["Frontend"]
  node_app_shell["App Shell<br/>Next.js app<br/>[page.tsx]"]
  node_game_ui["Game<br/>UI state<br/>[Game.jsx]"]
  node_word_input["Word Input<br/>input component<br/>[WordInput.jsx]"]
  node_word_chain["Word Chain<br/>display component<br/>[WordChain.jsx]"]
  node_results["Results<br/>result view<br/>[Results.jsx]"]
  node_howto["How To Play<br/>help panel<br/>[HowToPlay.jsx]"]
  node_api_client["API Client<br/>fetch layer<br/>[api.js]"]
  node_supabase_client[("Supabase<br/>client integration<br/>[supabase.js]")]
end

subgraph group_backend["Backend"]
  node_routes["Routes<br/>Flask REST<br/>[routes.py]"]
  node_game_service["Game Service<br/>orchestration<br/>[game_service.py]"]
  node_semantic_graph{{"Semantic Graph<br/>graph engine<br/>[semantic_graph.py]"}}
  node_embedding_service["Embeddings<br/>vector model"]
  node_word_database[("Word DB<br/>word inventory<br/>[word_database.py]")]
  node_run_entry["Run App<br/>service entrypoint<br/>[run.py]"]
end

subgraph group_infra["Infra"]
  node_ci_workflows["CI Workflows<br/>GitHub Actions<br/>[test-backend.yml]"]
  node_vercel(("Vercel<br/>frontend hosting"))
  node_railway(("Railway<br/>backend hosting"))
  node_supabase[("Supabase<br/>postgres service")]
end

node_browser(("Player<br/>browser client"))

node_browser -->|"uses"| node_app_shell
node_app_shell -->|"renders"| node_game_ui
node_game_ui -->|"captures"| node_word_input
node_game_ui -->|"updates"| node_word_chain
node_game_ui -->|"shows"| node_results
node_game_ui -->|"explains"| node_howto
node_game_ui -->|"calls"| node_api_client
node_api_client -->|"HTTP"| node_routes
node_routes -->|"orchestrates"| node_game_service
node_game_service -->|"queries"| node_semantic_graph
node_game_service -->|"builds"| node_embedding_service
node_game_service -->|"checks"| node_word_database
node_semantic_graph -->|"depends on"| node_embedding_service
node_semantic_graph -->|"expands from"| node_word_database
node_run_entry -->|"boots"| node_routes
node_ci_workflows -.->|"tests"| node_app_shell
node_ci_workflows -.->|"tests"| node_routes
node_app_shell -.->|"deploys to"| node_vercel
node_run_entry -.->|"deploys to"| node_railway
node_api_client -.->|"optional data"| node_supabase_client
node_supabase_client -.->|"connects"| node_supabase

click node_app_shell "https://github.com/apun16/6-degrees/blob/main/frontend/src/app/page.tsx"
click node_game_ui "https://github.com/apun16/6-degrees/blob/main/frontend/src/components/Game.jsx"
click node_word_input "https://github.com/apun16/6-degrees/blob/main/frontend/src/components/WordInput.jsx"
click node_word_chain "https://github.com/apun16/6-degrees/blob/main/frontend/src/components/WordChain.jsx"
click node_results "https://github.com/apun16/6-degrees/blob/main/frontend/src/components/Results.jsx"
click node_howto "https://github.com/apun16/6-degrees/blob/main/frontend/src/components/HowToPlay.jsx"
click node_api_client "https://github.com/apun16/6-degrees/blob/main/frontend/src/utils/api.js"
click node_supabase_client "https://github.com/apun16/6-degrees/blob/main/frontend/src/utils/supabase.js"
click node_routes "https://github.com/apun16/6-degrees/blob/main/backend/app/routes.py"
click node_game_service "https://github.com/apun16/6-degrees/blob/main/backend/app/game_service.py"
click node_semantic_graph "https://github.com/apun16/6-degrees/blob/main/backend/app/semantic_graph.py"
click node_embedding_service "https://github.com/apun16/6-degrees/blob/main/backend/app/embedding_service.py"
click node_word_database "https://github.com/apun16/6-degrees/blob/main/backend/app/word_database.py"
click node_run_entry "https://github.com/apun16/6-degrees/blob/main/backend/run.py"
click node_ci_workflows "https://github.com/apun16/6-degrees/blob/main/.github/workflows/test-backend.yml"

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_app_shell,node_game_ui,node_word_input,node_word_chain,node_results,node_howto,node_api_client,node_supabase_client toneBlue
class node_routes,node_game_service,node_semantic_graph,node_embedding_service,node_word_database,node_run_entry toneAmber
class node_ci_workflows,node_vercel,node_railway,node_supabase toneMint
class node_browser toneNeutral
```

## Components

### Frontend

Next.js UI, client state, and browser-side API boundary

- [App Shell](https://github.com/apun16/6-degrees/blob/main/frontend/src/app/page.tsx): Next.js app · Page and layout entry points · `frontend/src/app/page.tsx`
- [Game](https://github.com/apun16/6-degrees/blob/main/frontend/src/components/Game.jsx): UI state · Main gameplay controller and state holder · `frontend/src/components/Game.jsx`
- [Word Input](https://github.com/apun16/6-degrees/blob/main/frontend/src/components/WordInput.jsx): input component · Captures player guesses · `frontend/src/components/WordInput.jsx`
- [Word Chain](https://github.com/apun16/6-degrees/blob/main/frontend/src/components/WordChain.jsx): display component · Renders the current chain · `frontend/src/components/WordChain.jsx`
- [Results](https://github.com/apun16/6-degrees/blob/main/frontend/src/components/Results.jsx): result view · Shows completion and score · `frontend/src/components/Results.jsx`
- [How To Play](https://github.com/apun16/6-degrees/blob/main/frontend/src/components/HowToPlay.jsx): help panel · Explains the game rules · `frontend/src/components/HowToPlay.jsx`
- [API Client](https://github.com/apun16/6-degrees/blob/main/frontend/src/utils/api.js): fetch layer · All gameplay requests to the backend · `frontend/src/utils/api.js`
- [Supabase](https://github.com/apun16/6-degrees/blob/main/frontend/src/utils/supabase.js): client integration · Non-core app data or stats integration · `frontend/src/utils/supabase.js`

### Backend

Flask service and semantic game logic

- [Routes](https://github.com/apun16/6-degrees/blob/main/backend/app/routes.py): Flask REST · HTTP endpoints for gameplay actions · `backend/app/routes.py`
- [Game Service](https://github.com/apun16/6-degrees/blob/main/backend/app/game_service.py): orchestration · Coordinates rules, hints, scoring, and puzzle flow · `backend/app/game_service.py`
- [Semantic Graph](https://github.com/apun16/6-degrees/blob/main/backend/app/semantic_graph.py): graph engine · Builds and traverses word similarity links · `backend/app/semantic_graph.py`
- [Embeddings](https://github.com/apun16/6-degrees/blob/main/backend/app/embedding_service.py): vector model · Generates sentence embeddings and similarity inputs · `backend/app/embedding_service.py`
- [Word DB](https://github.com/apun16/6-degrees/blob/main/backend/app/word_database.py): word inventory · Valid-word lookup and preload set · `backend/app/word_database.py`
- [Run App](https://github.com/apun16/6-degrees/blob/main/backend/run.py): service entrypoint · Starts the Flask application · `backend/run.py`

### Infra

External services, CI, and deployment targets

- [CI Workflows](https://github.com/apun16/6-degrees/blob/main/.github/workflows/test-backend.yml): GitHub Actions · Separate frontend and backend test pipelines · `.github/workflows/test-backend.yml`
- **Vercel**: frontend hosting · Hosts the Next.js frontend
- **Railway**: backend hosting · Runs the containerized Flask backend
- **Supabase**: postgres service · External data layer used by the app

### Other components

- **Player**: browser client · User playing the word game

## Connections

- 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
