# alade017/osogbo-life-journey architecture

> Architecture diagram of the GitHub repository alade017/osogbo-life-journey, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-21). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/alade017/osogbo-life-journey
- Repository: https://github.com/alade017/osogbo-life-journey

## Overview

Osun Life is a browser-based life simulation in which players create a character, enter a shared town, travel between locations, and pursue housing, work, social, and recreational activities. The web routes and game services present and validate gameplay state; Supabase supplies persistent account and game data, while Colyseus rooms provide real-time multiplayer. The graph preserves the documented gameplay branches and principal world-rendering layers. Several capabilities are documented but their detailed implementation was not sampled, so those links are cited to the README.

Main entry points: [`multiplayer/server.ts`](https://github.com/alade017/osogbo-life-journey/blob/main/multiplayer/server.ts) (Room server), [`src/routes/_authenticated/_game.tsx`](https://github.com/alade017/osogbo-life-journey/blob/main/src/routes/_authenticated/_game.tsx) (Game shell), [`src/components/map/R3FTownSurface.tsx`](https://github.com/alade017/osogbo-life-journey/blob/main/src/components/map/R3FTownSurface.tsx) (Town map surface), [`src/lib/game.ts`](https://github.com/alade017/osogbo-life-journey/blob/main/src/lib/game.ts) (Game services)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry and routing"]
  node_entry["Entry and auth<br/>[index.tsx]"]
  node_character["Character creation"]
  node_router["Authenticated routes<br/>[routeTree.gen.ts]"]
  node_game_shell["Game shell<br/>[_game.tsx]"]
end

subgraph group_world["Town and world"]
  node_town_data["Town model<br/>[city-world.ts]"]
  node_map_surface["Town map surface<br/>[R3FTownSurface.tsx]"]
  node_world_scene["3D world scene<br/>[WorldScene.tsx]"]
  node_world_theme["World theme<br/>[world-theme.ts]"]
  node_neighborhood["Neighborhood model"]
  node_travel["Town travel"]
  node_city_dashboard["City dashboard"]
end

subgraph group_gameplay["Life simulation"]
  node_life_routes["Jobs and schooling<br/>[jobs.tsx]"]
  node_housing["Housing<br/>[house.tsx]"]
  node_party["Party life<br/>[party.tsx]"]
  node_mini_games["Mini-games<br/>[ludo-engine.ts]"]
  node_messaging["Messaging<br/>[send.ts]"]
  node_game_services["Game services<br/>[game.ts]"]
end

subgraph group_platform["Persistence and multiplayer"]
  node_supabase_client["Supabase client<br/>[client.ts]"]
  node_multiplayer_server["Room server<br/>[server.ts]"]
  node_neighborhood_room["Neighborhood room"]
  node_party_room["Party room<br/>[party-room.ts]"]
  node_ludo_room["Ludo room<br/>[ludo-room.ts]"]
  node_mall_room["Mall room<br/>[mall-room.ts]"]
end

node_player(("Player"))

node_player -->|"opens"| node_entry
node_entry -->|"starts character"| node_character
node_character -->|"enters town"| node_game_shell
node_game_shell -->|"uses routes"| node_router
node_game_shell -.->|"presents"| node_city_dashboard
node_city_dashboard -.->|"shows map"| node_map_surface
node_map_surface -.->|"renders town"| node_town_data
node_map_surface -.->|"initiates travel"| node_travel
node_world_scene -->|"uses theme"| node_world_theme
node_player -->|"pursues work"| node_life_routes
node_player -->|"rents home"| node_housing
node_player -->|"attends events"| node_party
node_player -->|"plays games"| node_mini_games
node_player -->|"sends messages"| node_messaging
node_life_routes -.->|"uses game data"| node_game_services
node_housing -.->|"uses game data"| node_game_services
node_game_services -->|"queries and mutates"| node_supabase_client
node_multiplayer_server -->|"registers"| node_neighborhood_room
node_multiplayer_server -->|"registers"| node_party_room
node_multiplayer_server -->|"registers"| node_ludo_room
node_multiplayer_server -->|"registers"| node_mall_room
node_player -->|"joins shared world"| node_multiplayer_server
node_neighborhood_room -->|"uses world model"| node_neighborhood
node_ludo_room -->|"uses rules engine"| node_mini_games

click node_entry "https://github.com/alade017/osogbo-life-journey/blob/main/src/routes/index.tsx"
click node_character "https://github.com/alade017/osogbo-life-journey/blob/main/src/routes/_authenticated/create-character.tsx"
click node_router "https://github.com/alade017/osogbo-life-journey/blob/main/src/routeTree.gen.ts"
click node_game_shell "https://github.com/alade017/osogbo-life-journey/blob/main/src/routes/_authenticated/_game.tsx"
click node_town_data "https://github.com/alade017/osogbo-life-journey/blob/main/src/lib/city-world.ts"
click node_map_surface "https://github.com/alade017/osogbo-life-journey/blob/main/src/components/map/R3FTownSurface.tsx"
click node_world_scene "https://github.com/alade017/osogbo-life-journey/blob/main/src/components/3d/WorldScene.tsx"
click node_world_theme "https://github.com/alade017/osogbo-life-journey/blob/main/src/components/3d/world-theme.ts"
click node_neighborhood "https://github.com/alade017/osogbo-life-journey/blob/main/src/game/neighborhood-model.ts"
click node_travel "https://github.com/alade017/osogbo-life-journey/blob/main/src/lib/transport-service.ts"
click node_city_dashboard "https://github.com/alade017/osogbo-life-journey/blob/main/src/components/game/CityMapDashboard.tsx"
click node_life_routes "https://github.com/alade017/osogbo-life-journey/blob/main/src/routes/_authenticated/_game/jobs.tsx"
click node_housing "https://github.com/alade017/osogbo-life-journey/blob/main/src/routes/_authenticated/_game/house.tsx"
click node_party "https://github.com/alade017/osogbo-life-journey/blob/main/src/routes/_authenticated/_game/party.tsx"
click node_mini_games "https://github.com/alade017/osogbo-life-journey/blob/main/src/lib/mini-games/ludo-engine.ts"
click node_messaging "https://github.com/alade017/osogbo-life-journey/blob/main/src/routes/api/messages/send.ts"
click node_game_services "https://github.com/alade017/osogbo-life-journey/blob/main/src/lib/game.ts"
click node_supabase_client "https://github.com/alade017/osogbo-life-journey/blob/main/src/integrations/supabase/client.ts"
click node_multiplayer_server "https://github.com/alade017/osogbo-life-journey/blob/main/multiplayer/server.ts"
click node_neighborhood_room "https://github.com/alade017/osogbo-life-journey/blob/main/multiplayer/neighborhood-room.ts"
click node_party_room "https://github.com/alade017/osogbo-life-journey/blob/main/multiplayer/party-room.ts"
click node_ludo_room "https://github.com/alade017/osogbo-life-journey/blob/main/multiplayer/ludo-room.ts"
click node_mall_room "https://github.com/alade017/osogbo-life-journey/blob/main/multiplayer/mall-room.ts"

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_entry,node_character,node_router,node_game_shell toneBlue
class node_town_data,node_map_surface,node_world_scene,node_world_theme,node_neighborhood,node_travel,node_city_dashboard toneAmber
class node_life_routes,node_housing,node_party,node_mini_games,node_messaging,node_game_services toneMint
class node_supabase_client,node_multiplayer_server,node_neighborhood_room,node_party_room,node_ludo_room,node_mall_room toneRose
class node_player toneIndigo
```

## Components

### Entry and routing

- [Entry and auth](https://github.com/alade017/osogbo-life-journey/blob/main/src/routes/index.tsx): `src/routes/index.tsx`
- [Character creation](https://github.com/alade017/osogbo-life-journey/blob/main/src/routes/_authenticated/create-character.tsx): `src/routes/_authenticated/create-character.tsx`
- [Authenticated routes](https://github.com/alade017/osogbo-life-journey/blob/main/src/routeTree.gen.ts): `src/routeTree.gen.ts`
- [Game shell](https://github.com/alade017/osogbo-life-journey/blob/main/src/routes/_authenticated/_game.tsx): `src/routes/_authenticated/_game.tsx`

### Town and world

- [Town model](https://github.com/alade017/osogbo-life-journey/blob/main/src/lib/city-world.ts): `src/lib/city-world.ts`
- [Town map surface](https://github.com/alade017/osogbo-life-journey/blob/main/src/components/map/R3FTownSurface.tsx): `src/components/map/R3FTownSurface.tsx`
- [3D world scene](https://github.com/alade017/osogbo-life-journey/blob/main/src/components/3d/WorldScene.tsx): `src/components/3d/WorldScene.tsx`
- [World theme](https://github.com/alade017/osogbo-life-journey/blob/main/src/components/3d/world-theme.ts): `src/components/3d/world-theme.ts`
- [Neighborhood model](https://github.com/alade017/osogbo-life-journey/blob/main/src/game/neighborhood-model.ts): `src/game/neighborhood-model.ts`
- [Town travel](https://github.com/alade017/osogbo-life-journey/blob/main/src/lib/transport-service.ts): `src/lib/transport-service.ts`
- [City dashboard](https://github.com/alade017/osogbo-life-journey/blob/main/src/components/game/CityMapDashboard.tsx): `src/components/game/CityMapDashboard.tsx`

### Life simulation

- [Jobs and schooling](https://github.com/alade017/osogbo-life-journey/blob/main/src/routes/_authenticated/_game/jobs.tsx): `src/routes/_authenticated/_game/jobs.tsx`
- [Housing](https://github.com/alade017/osogbo-life-journey/blob/main/src/routes/_authenticated/_game/house.tsx): `src/routes/_authenticated/_game/house.tsx`
- [Party life](https://github.com/alade017/osogbo-life-journey/blob/main/src/routes/_authenticated/_game/party.tsx): `src/routes/_authenticated/_game/party.tsx`
- [Mini-games](https://github.com/alade017/osogbo-life-journey/blob/main/src/lib/mini-games/ludo-engine.ts): `src/lib/mini-games/ludo-engine.ts`
- [Messaging](https://github.com/alade017/osogbo-life-journey/blob/main/src/routes/api/messages/send.ts): `src/routes/api/messages/send.ts`
- [Game services](https://github.com/alade017/osogbo-life-journey/blob/main/src/lib/game.ts): `src/lib/game.ts`

### Persistence and multiplayer

- [Supabase client](https://github.com/alade017/osogbo-life-journey/blob/main/src/integrations/supabase/client.ts): `src/integrations/supabase/client.ts`
- [Room server](https://github.com/alade017/osogbo-life-journey/blob/main/multiplayer/server.ts): `multiplayer/server.ts`
- [Neighborhood room](https://github.com/alade017/osogbo-life-journey/blob/main/multiplayer/neighborhood-room.ts): `multiplayer/neighborhood-room.ts`
- [Party room](https://github.com/alade017/osogbo-life-journey/blob/main/multiplayer/party-room.ts): `multiplayer/party-room.ts`
- [Ludo room](https://github.com/alade017/osogbo-life-journey/blob/main/multiplayer/ludo-room.ts): `multiplayer/ludo-room.ts`
- [Mall room](https://github.com/alade017/osogbo-life-journey/blob/main/multiplayer/mall-room.ts): `multiplayer/mall-room.ts`

### Other components

- **Player**

## Connections

- Player → Entry and auth: opens
- Entry and auth → Character creation: starts character
- Character creation → Game shell: enters town
- Game shell → Authenticated routes: uses routes (evidence: `src/routeTree.gen.ts`)
- Game shell → City dashboard: presents
- City dashboard → Town map surface: shows map
- Town map surface → Town model: renders town
- Town map surface → Town travel: initiates travel
- 3D world scene → World theme: uses theme (evidence: `src/components/3d/WorldScene.tsx`)
- Player → Jobs and schooling: pursues work
- Player → Housing: rents home
- Player → Party life: attends events
- Player → Mini-games: plays games
- Player → Messaging: sends messages
- Jobs and schooling → Game services: uses game data
- Housing → Game services: uses game data
- Game services → Supabase client: queries and mutates (evidence: `src/lib/game.ts`)
- Room server → Neighborhood room: registers (evidence: `multiplayer/server.ts`)
- Room server → Party room: registers (evidence: `multiplayer/server.ts`)
- Room server → Ludo room: registers (evidence: `multiplayer/server.ts`)
- Room server → Mall room: registers (evidence: `multiplayer/server.ts`)
- Player → Room server: joins shared world
- Neighborhood room → Neighborhood model: uses world model (evidence: `multiplayer/neighborhood-room.ts`)
- Ludo room → Mini-games: uses rules engine (evidence: `multiplayer/ludo-room.ts`)
