# brian-w-m/devverse architecture

> Architecture diagram of the GitHub repository brian-w-m/devverse, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/brian-w-m/devverse
- Repository: https://github.com/brian-w-m/devverse

## Overview

DevVerse combines a coding-activity tracker with a web dashboard and a Pixel Quest RPG experience. The principal documented workflow is VS Code edit tracking and score submission to the Go API, followed by DynamoDB-backed user/activity data displayed in the dashboard; GitHub login supplies identity. The README also describes leaderboard/streak features and the game reward loop. Backend auth and persistence calls are supported by sampled source; route wiring and several frontend/extension internals are not sampled, so uncertain links are omitted.

Main entry points: [`backend/src/routes/register.go`](https://github.com/brian-w-m/devverse/blob/main/backend/src/routes/register.go) (API Routes), [`frontend/app/page.tsx`](https://github.com/brian-w-m/devverse/blob/main/frontend/app/page.tsx) (Web App), [`backend/src/routes/auth.go`](https://github.com/brian-w-m/devverse/blob/main/backend/src/routes/auth.go) (Auth Route), [`frontend/app/api/auth/github/token/route.ts`](https://github.com/brian-w-m/devverse/blob/main/frontend/app/api/auth/github/token/route.ts) (OAuth Token Exchange)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["User Clients"]
  node_vscode["VS Code"]
  node_extension["Edit Tracker<br/>[extension.ts]"]
  node_web["Web App<br/>[page.tsx]"]
  node_dashboard["Dashboard<br/>[page.tsx]"]
  node_game["Pixel Quest<br/>[page.tsx]"]
  node_phaser["Game Prototype<br/>[page.tsx]"]
end

subgraph group_identity["Identity"]
  node_oauth_route["OAuth Token Exchange<br/>[route.ts]"]
end

subgraph group_api["Backend API"]
  node_server["HTTP Server<br/>[main.go]"]
  node_routes["API Routes<br/>[register.go]"]
  node_auth_route["Auth Route<br/>[auth.go]"]
  node_auth_service["Auth Service<br/>[auth_service.go]"]
  node_user_service["User Service<br/>[user_service.go]"]
  node_job_routes["Activity Routes<br/>[jobs.go]"]
  node_job_service["Activity Service<br/>[job_service.go]"]
  node_stats_routes["Stats Routes<br/>[stats.go]"]
  node_stats_service["Stats Service<br/>[stats_service.go]"]
  node_session_service["Session Service<br/>[session_service.go]"]
end

subgraph group_data["Activity Data"]
  node_dynamodb[("DynamoDB")]
end

node_developer(("Developer"))
node_github["GitHub"]

node_developer -->|"edits code"| node_vscode
node_vscode -->|"activates"| node_extension
node_extension -->|"submits scores"| node_server
node_developer -->|"uses"| node_web
node_web -->|"exchanges code"| node_oauth_route
node_oauth_route -->|"requests token"| node_github
node_github -->|"returns token"| node_oauth_route
node_web -->|"opens"| node_dashboard
node_dashboard -->|"requests stats"| node_stats_routes
node_developer -->|"plays"| node_game
node_game -.->|"prototype"| node_phaser
node_server -->|"registers"| node_routes
node_routes -->|"dispatches"| node_auth_route
node_auth_route -->|"verifies token"| node_auth_service
node_auth_service -->|"verifies identity"| node_github
node_auth_route -->|"creates or updates"| node_user_service
node_routes -->|"dispatches"| node_job_routes
node_job_routes -->|"handles activity"| node_job_service
node_routes -->|"dispatches"| node_stats_routes
node_stats_routes -->|"queries stats"| node_stats_service
node_stats_service -->|"reads users"| node_dynamodb
node_user_service -->|"reads and writes"| node_dynamodb
node_job_service -.->|"updates scores"| node_user_service
node_session_service -->|"records activity"| node_dynamodb

click node_extension "https://github.com/brian-w-m/devverse/blob/main/extension/src/extension.ts"
click node_web "https://github.com/brian-w-m/devverse/blob/main/frontend/app/page.tsx"
click node_dashboard "https://github.com/brian-w-m/devverse/blob/main/frontend/app/dashboard/page.tsx"
click node_game "https://github.com/brian-w-m/devverse/blob/main/frontend/app/game/page.tsx"
click node_phaser "https://github.com/brian-w-m/devverse/blob/main/frontend/app/phaser-test/page.tsx"
click node_oauth_route "https://github.com/brian-w-m/devverse/blob/main/frontend/app/api/auth/github/token/route.ts"
click node_server "https://github.com/brian-w-m/devverse/blob/main/backend/src/main.go"
click node_routes "https://github.com/brian-w-m/devverse/blob/main/backend/src/routes/register.go"
click node_auth_route "https://github.com/brian-w-m/devverse/blob/main/backend/src/routes/auth.go"
click node_auth_service "https://github.com/brian-w-m/devverse/blob/main/backend/src/services/auth_service.go"
click node_user_service "https://github.com/brian-w-m/devverse/blob/main/backend/src/services/user_service.go"
click node_job_routes "https://github.com/brian-w-m/devverse/blob/main/backend/src/routes/jobs.go"
click node_job_service "https://github.com/brian-w-m/devverse/blob/main/backend/src/services/job_service.go"
click node_stats_routes "https://github.com/brian-w-m/devverse/blob/main/backend/src/routes/stats.go"
click node_stats_service "https://github.com/brian-w-m/devverse/blob/main/backend/src/services/stats_service.go"
click node_session_service "https://github.com/brian-w-m/devverse/blob/main/backend/src/services/session_service.go"

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_vscode,node_extension,node_web,node_dashboard,node_game,node_phaser toneBlue
class node_oauth_route toneAmber
class node_server,node_routes,node_auth_route,node_auth_service,node_user_service,node_job_routes,node_job_service,node_stats_routes,node_stats_service,node_session_service toneMint
class node_dynamodb toneRose
class node_developer,node_github toneIndigo
```

## Components

### User Clients

- **VS Code**
- [Edit Tracker](https://github.com/brian-w-m/devverse/blob/main/extension/src/extension.ts): `extension/src/extension.ts`
- [Web App](https://github.com/brian-w-m/devverse/blob/main/frontend/app/page.tsx): `frontend/app/page.tsx`
- [Dashboard](https://github.com/brian-w-m/devverse/blob/main/frontend/app/dashboard/page.tsx): `frontend/app/dashboard/page.tsx`
- [Pixel Quest](https://github.com/brian-w-m/devverse/blob/main/frontend/app/game/page.tsx): `frontend/app/game/page.tsx`
- [Game Prototype](https://github.com/brian-w-m/devverse/blob/main/frontend/app/phaser-test/page.tsx): `frontend/app/phaser-test/page.tsx`

### Identity

- [OAuth Token Exchange](https://github.com/brian-w-m/devverse/blob/main/frontend/app/api/auth/github/token/route.ts): `frontend/app/api/auth/github/token/route.ts`

### Backend API

- [HTTP Server](https://github.com/brian-w-m/devverse/blob/main/backend/src/main.go): `backend/src/main.go`
- [API Routes](https://github.com/brian-w-m/devverse/blob/main/backend/src/routes/register.go): `backend/src/routes/register.go`
- [Auth Route](https://github.com/brian-w-m/devverse/blob/main/backend/src/routes/auth.go): `backend/src/routes/auth.go`
- [Auth Service](https://github.com/brian-w-m/devverse/blob/main/backend/src/services/auth_service.go): `backend/src/services/auth_service.go`
- [User Service](https://github.com/brian-w-m/devverse/blob/main/backend/src/services/user_service.go): `backend/src/services/user_service.go`
- [Activity Routes](https://github.com/brian-w-m/devverse/blob/main/backend/src/routes/jobs.go): `backend/src/routes/jobs.go`
- [Activity Service](https://github.com/brian-w-m/devverse/blob/main/backend/src/services/job_service.go): `backend/src/services/job_service.go`
- [Stats Routes](https://github.com/brian-w-m/devverse/blob/main/backend/src/routes/stats.go): `backend/src/routes/stats.go`
- [Stats Service](https://github.com/brian-w-m/devverse/blob/main/backend/src/services/stats_service.go): `backend/src/services/stats_service.go`
- [Session Service](https://github.com/brian-w-m/devverse/blob/main/backend/src/services/session_service.go): `backend/src/services/session_service.go`

### Activity Data

- **DynamoDB**

### Other components

- **Developer**
- **GitHub**

## Connections

- Developer → VS Code: edits code
- VS Code → Edit Tracker: activates
- Edit Tracker → HTTP Server: submits scores
- Developer → Web App: uses
- Web App → OAuth Token Exchange: exchanges code
- OAuth Token Exchange → GitHub: requests token
- GitHub → OAuth Token Exchange: returns token
- Web App → Dashboard: opens
- Dashboard → Stats Routes: requests stats
- Developer → Pixel Quest: plays
- Pixel Quest → Game Prototype: prototype
- HTTP Server → API Routes: registers
- API Routes → Auth Route: dispatches
- Auth Route → Auth Service: verifies token
- Auth Service → GitHub: verifies identity
- Auth Route → User Service: creates or updates
- API Routes → Activity Routes: dispatches
- Activity Routes → Activity Service: handles activity
- API Routes → Stats Routes: dispatches
- Stats Routes → Stats Service: queries stats
- Stats Service → DynamoDB: reads users
- User Service → DynamoDB: reads and writes
- Activity Service → User Service: updates scores
- Session Service → DynamoDB: records activity