# romeirofernandes/typiks architecture

> Architecture diagram of the GitHub repository romeirofernandes/typiks, 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/romeirofernandes/typiks
- Repository: https://github.com/romeirofernandes/typiks

## Overview

#### Purpose and entry points
This is a full-stack, real-time multiplayer game application with user profiles, ratings, public/private rooms, presence, geographic data, and a React game UI. The frontend starts at `frontend/src/main.jsx` and composes routing/application state in `frontend/src/App.jsx`. The backend HTTP/Worker entry point is `backend/src/index.js`.

#### Frontend application shell
The Vite React client provides public landing/auth flows plus authenticated game and social views. Route-level screens include gameplay, matchmaking/room creation, waiting-room, dashboard, leaderboard, profile, friends, bot mode, and globe views:
- `frontend/src/pages/Game.jsx`
- `frontend/src/pages/StartGame.jsx`
- `frontend/src/pages/WaitingRoom.jsx`

Authenticated navigation is gated by `frontend/src/components/ProtectedRoute.jsx`; Firebase client initialization and auth state are centralized in `frontend/src/firebase.js` and `frontend/src/context/AuthContext.jsx`.

#### Backend API and authentication boundary
The backend exposes user and room-oriented HTTP APIs through:
- `backend/src/index.js`
- `backend/src/routes/users.js`
- `backend/src/routes/rooms.js`

Firebase identity is verified at the server boundary by `backend/src/middleware/firebaseAuth.js`. This separates client-side Firebase session handling from trusted backend authorization before profile, room, or game-related operations proceed.

#### Real-time game and presence layer
Cloudflare Durable Objects appear to own mutable, connection-oriented runtime state rather than placing active matches in ordinary request handlers:
- `backend/src/durable-objects/GameRoom.js`
- `backend/src/durable-objects/PrivateRoom.js`
- `backend/src/durable-objects/PresenceHub.js`

Room APIs likely resolve or create the appropriate durable object, while `GameRoom` manages shared match lifecycle/state, `PrivateRoom` supports invite/private sessions, and `PresenceHub` tracks online availability. This is the primary real-time control boundary.

#### Persistent domain data and progression
Relational persistence is defined in `backend/src/db/schema.js` and evolved through Drizzle migrations under `backend/migrations/`, including rating, profile location, presence/invites, and avatar changes. Rating/progression logic is isolated in `backend/src/utils/rating.js`, allowing game completion state to feed durable-room coordination and then durable profile/ranking storage.

Game content/supporting data includes country geography and generated words:
- `backend/src/countries-geo.json`
- `backend/src/utils/wordGenerator.js`
- `words.json`

#### Player-facing data visualization and presentation
Dashboard/profile-oriented views expose player history and relationships, with reusable rating/type chart components:
- `frontend/src/pages/Dashboard.jsx`
- `frontend/src/pages/Profile.jsx`
- `frontend/src/components/charts/RatingGrowthChart.jsx`

The gameplay client is distinct from the marketing/auth surface, with landing composition in `frontend/src/pages/NewLanding.jsx` and game interaction concentrated in `frontend/src/pages/Game.jsx`.

#### Runtime and deployment infrastructure
The backend is configured as a Cloudflare Worker/Durable Objects deployment via `backend/wrangler.jsonc`, with Drizzle configuration in `backend/drizzle.config.js`. The frontend is a Vite build and has Vercel deployment configuration at `frontend/vercel.json`. Firebase is an external authentication service; the backend also depends on a database compatible with the Drizzle schema and migration set.

Main entry points: [`backend/src/index.js`](https://github.com/romeirofernandes/typiks/blob/main/backend/src/index.js) (Worker HTTP entry), [`frontend/src/components/ProtectedRoute.jsx`](https://github.com/romeirofernandes/typiks/blob/main/frontend/src/components/ProtectedRoute.jsx) (Protected routes), [`backend/src/middleware/firebaseAuth.js`](https://github.com/romeirofernandes/typiks/blob/main/backend/src/middleware/firebaseAuth.js) (Server auth verification), [`backend/src/routes/rooms.js`](https://github.com/romeirofernandes/typiks/blob/main/backend/src/routes/rooms.js) (Room API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_frontend["React Client"]
  node_client_entry["Client entry<br/>Vite entry<br/>[main.jsx]"]
  node_app_shell["App routing shell<br/>React app<br/>[App.jsx]"]
  node_auth_context["Auth session<br/>React context<br/>[AuthContext.jsx]"]
  node_firebase_client["Firebase client<br/>Auth SDK setup<br/>[firebase.js]"]
  node_protected_routes["Protected routes<br/>Route guard<br/>[ProtectedRoute.jsx]"]
  node_game_ui["Gameplay UI<br/>React screen<br/>[Game.jsx]"]
  node_room_flow["Matchmaking &amp; lobby<br/>React screens<br/>[StartGame.jsx]"]
  node_dashboard_profile["Dashboard &amp; profile<br/>React views<br/>[Dashboard.jsx]"]
end

subgraph group_backend["Worker Backend"]
  node_worker_entry{{"Worker HTTP entry<br/>Cloudflare Worker<br/>[index.js]"}}
  node_firebase_auth["Server auth verification<br/>Auth middleware<br/>[firebaseAuth.js]"]
  node_user_api["User API<br/>HTTP routes<br/>[users.js]"]
  node_room_api["Room API<br/>HTTP routes<br/>[rooms.js]"]
  node_worker_deployment["Worker deployment<br/>Cloudflare config<br/>[wrangler.jsonc]"]
end

subgraph group_realtime["Real-time Objects"]
  node_game_room{{"Game room<br/>Durable Object<br/>[GameRoom.js]"}}
  node_private_room{{"Private room<br/>Durable Object<br/>[PrivateRoom.js]"}}
  node_presence_hub{{"Presence hub<br/>Durable Object<br/>[PresenceHub.js]"}}
end

subgraph group_data["Persistence &amp; Content"]
  node_domain_database[("Domain database<br/>Drizzle relational data<br/>[schema.js]")]
  node_rating_logic["Rating progression<br/>Domain logic<br/>[rating.js]"]
  node_game_content["Game content<br/>Geography &amp; words<br/>[countries-geo.json]"]
end

node_firebase_service(("Firebase<br/>External identity service"))

node_client_entry -->|"mounts"| node_app_shell
node_app_shell -->|"uses session"| node_auth_context
node_auth_context -->|"initializes through"| node_firebase_client
node_firebase_client -->|"authenticates with"| node_firebase_service
node_app_shell -->|"gates"| node_protected_routes
node_protected_routes -->|"allows"| node_game_ui
node_protected_routes -->|"allows"| node_room_flow
node_protected_routes -->|"allows"| node_dashboard_profile
node_game_ui -->|"game requests"| node_worker_entry
node_room_flow -->|"room requests"| node_worker_entry
node_dashboard_profile -->|"profile requests"| node_worker_entry
node_worker_entry -->|"protects requests with"| node_firebase_auth
node_firebase_auth -->|"verifies tokens with"| node_firebase_service
node_firebase_auth -->|"authorizes"| node_user_api
node_firebase_auth -->|"authorizes"| node_room_api
node_user_api -->|"reads and writes"| node_domain_database
node_room_api -->|"creates or resolves"| node_game_room
node_room_api -->|"creates or resolves"| node_private_room
node_room_api -->|"queries presence"| node_presence_hub
node_game_room -->|"on match completion"| node_rating_logic
node_rating_logic -->|"updates ratings"| node_domain_database
node_game_room -->|"uses"| node_game_content
node_worker_deployment -.->|"deploys"| node_worker_entry

click node_client_entry "https://github.com/romeirofernandes/typiks/blob/main/frontend/src/main.jsx"
click node_app_shell "https://github.com/romeirofernandes/typiks/blob/main/frontend/src/App.jsx"
click node_auth_context "https://github.com/romeirofernandes/typiks/blob/main/frontend/src/context/AuthContext.jsx"
click node_firebase_client "https://github.com/romeirofernandes/typiks/blob/main/frontend/src/firebase.js"
click node_protected_routes "https://github.com/romeirofernandes/typiks/blob/main/frontend/src/components/ProtectedRoute.jsx"
click node_game_ui "https://github.com/romeirofernandes/typiks/blob/main/frontend/src/pages/Game.jsx"
click node_room_flow "https://github.com/romeirofernandes/typiks/blob/main/frontend/src/pages/StartGame.jsx"
click node_dashboard_profile "https://github.com/romeirofernandes/typiks/blob/main/frontend/src/pages/Dashboard.jsx"
click node_worker_entry "https://github.com/romeirofernandes/typiks/blob/main/backend/src/index.js"
click node_firebase_auth "https://github.com/romeirofernandes/typiks/blob/main/backend/src/middleware/firebaseAuth.js"
click node_user_api "https://github.com/romeirofernandes/typiks/blob/main/backend/src/routes/users.js"
click node_room_api "https://github.com/romeirofernandes/typiks/blob/main/backend/src/routes/rooms.js"
click node_game_room "https://github.com/romeirofernandes/typiks/blob/main/backend/src/durable-objects/GameRoom.js"
click node_private_room "https://github.com/romeirofernandes/typiks/blob/main/backend/src/durable-objects/PrivateRoom.js"
click node_presence_hub "https://github.com/romeirofernandes/typiks/blob/main/backend/src/durable-objects/PresenceHub.js"
click node_domain_database "https://github.com/romeirofernandes/typiks/blob/main/backend/src/db/schema.js"
click node_rating_logic "https://github.com/romeirofernandes/typiks/blob/main/backend/src/utils/rating.js"
click node_game_content "https://github.com/romeirofernandes/typiks/blob/main/backend/src/countries-geo.json"
click node_worker_deployment "https://github.com/romeirofernandes/typiks/blob/main/backend/wrangler.jsonc"

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_client_entry,node_app_shell,node_auth_context,node_firebase_client,node_protected_routes,node_game_ui,node_room_flow,node_dashboard_profile toneBlue
class node_worker_entry,node_firebase_auth,node_user_api,node_room_api,node_worker_deployment toneAmber
class node_game_room,node_private_room,node_presence_hub toneMint
class node_domain_database,node_rating_logic,node_game_content toneRose
class node_firebase_service toneNeutral
```

## Components

### React Client

- [Client entry](https://github.com/romeirofernandes/typiks/blob/main/frontend/src/main.jsx): Vite entry · `frontend/src/main.jsx`
- [App routing shell](https://github.com/romeirofernandes/typiks/blob/main/frontend/src/App.jsx): React app · Composes public and authenticated views. · `frontend/src/App.jsx`
- [Auth session](https://github.com/romeirofernandes/typiks/blob/main/frontend/src/context/AuthContext.jsx): React context · Centralizes Firebase client auth state. · `frontend/src/context/AuthContext.jsx`
- [Firebase client](https://github.com/romeirofernandes/typiks/blob/main/frontend/src/firebase.js): Auth SDK setup · `frontend/src/firebase.js`
- [Protected routes](https://github.com/romeirofernandes/typiks/blob/main/frontend/src/components/ProtectedRoute.jsx): Route guard · `frontend/src/components/ProtectedRoute.jsx`
- [Gameplay UI](https://github.com/romeirofernandes/typiks/blob/main/frontend/src/pages/Game.jsx): React screen · `frontend/src/pages/Game.jsx`
- [Matchmaking & lobby](https://github.com/romeirofernandes/typiks/blob/main/frontend/src/pages/StartGame.jsx): React screens · Creates rooms and waits for matches. · `frontend/src/pages/StartGame.jsx`
- [Dashboard & profile](https://github.com/romeirofernandes/typiks/blob/main/frontend/src/pages/Dashboard.jsx): React views · Shows player history, relationships, and progression. · `frontend/src/pages/Dashboard.jsx`

### Worker Backend

- [Worker HTTP entry](https://github.com/romeirofernandes/typiks/blob/main/backend/src/index.js): Cloudflare Worker · `backend/src/index.js`
- [Server auth verification](https://github.com/romeirofernandes/typiks/blob/main/backend/src/middleware/firebaseAuth.js): Auth middleware · Verifies Firebase identity before protected operations. · `backend/src/middleware/firebaseAuth.js`
- [User API](https://github.com/romeirofernandes/typiks/blob/main/backend/src/routes/users.js): HTTP routes · `backend/src/routes/users.js`
- [Room API](https://github.com/romeirofernandes/typiks/blob/main/backend/src/routes/rooms.js): HTTP routes · Resolves or creates real-time room instances. · `backend/src/routes/rooms.js`
- [Worker deployment](https://github.com/romeirofernandes/typiks/blob/main/backend/wrangler.jsonc): Cloudflare config · Binds the Worker and Durable Objects runtime. · `backend/wrangler.jsonc`

### Real-time Objects

- [Game room](https://github.com/romeirofernandes/typiks/blob/main/backend/src/durable-objects/GameRoom.js): Durable Object · Owns shared active-match lifecycle and state. · `backend/src/durable-objects/GameRoom.js`
- [Private room](https://github.com/romeirofernandes/typiks/blob/main/backend/src/durable-objects/PrivateRoom.js): Durable Object · Supports invite-only sessions. · `backend/src/durable-objects/PrivateRoom.js`
- [Presence hub](https://github.com/romeirofernandes/typiks/blob/main/backend/src/durable-objects/PresenceHub.js): Durable Object · Tracks online player availability. · `backend/src/durable-objects/PresenceHub.js`

### Persistence & Content

- [Domain database](https://github.com/romeirofernandes/typiks/blob/main/backend/src/db/schema.js): Drizzle relational data · Stores profiles, ratings, locations, invites, and history. · `backend/src/db/schema.js`
- [Rating progression](https://github.com/romeirofernandes/typiks/blob/main/backend/src/utils/rating.js): Domain logic · Calculates persistent rating changes after matches. · `backend/src/utils/rating.js`
- [Game content](https://github.com/romeirofernandes/typiks/blob/main/backend/src/countries-geo.json): Geography & words · Country geography and generated-word support. · `backend/src/countries-geo.json`

### Other components

- **Firebase**: External identity service

## Connections

- Client entry → App routing shell: mounts
- App routing shell → Auth session: uses session
- Auth session → Firebase client: initializes through
- Firebase client → Firebase: authenticates with
- App routing shell → Protected routes: gates
- Protected routes → Gameplay UI: allows
- Protected routes → Matchmaking & lobby: allows
- Protected routes → Dashboard & profile: allows
- Gameplay UI → Worker HTTP entry: game requests
- Matchmaking & lobby → Worker HTTP entry: room requests
- Dashboard & profile → Worker HTTP entry: profile requests
- Worker HTTP entry → Server auth verification: protects requests with
- Server auth verification → Firebase: verifies tokens with
- Server auth verification → User API: authorizes
- Server auth verification → Room API: authorizes
- User API → Domain database: reads and writes
- Room API → Game room: creates or resolves
- Room API → Private room: creates or resolves
- Room API → Presence hub: queries presence
- Game room → Rating progression: on match completion
- Rating progression → Domain database: updates ratings
- Game room → Game content: uses
- Worker deployment → Worker HTTP entry: deploys