# osutitanic/titanic architecture

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

## Overview

Titanic’s sampled Go product surface comprises Stern, the website for an osu! private server, and Jobs, its background task runner, backed by shared domain and persistence packages. The user-facing path begins with a browser request, reaches Stern’s HTTP routes, and returns rendered pages; the route tree documents account, forum, beatmap, ranking, and wiki features. Jobs provides a separate scheduled-task capability. Several route and task implementations were not sampled, so links from them into shared services are omitted where ownership cannot be verified.

Main entry points: [`services/stern/cmd/web/main.go`](https://github.com/osutitanic/titanic/blob/main/services/stern/cmd/web/main.go) (Stern HTTP server), [`services/stern/internal/wiki/service.go`](https://github.com/osutitanic/titanic/blob/main/services/stern/internal/wiki/service.go) (Wiki service), [`services/jobs/cmd/cli/main.go`](https://github.com/osutitanic/titanic/blob/main/services/jobs/cmd/cli/main.go) (Jobs command), [`services/stern/internal/routes`](https://github.com/osutitanic/titanic/tree/main/services/stern/internal/routes) (Website routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Stern Website"]
  node_stern["Stern HTTP server<br/>[main.go]"]
  node_routes["Website routes"]
  node_templates["Page rendering<br/>[engine.go]"]
  node_static["Browser scripts"]
  node_wiki["Wiki service<br/>[service.go]"]
  node_account_routes["Account routes<br/>[account_login.go]"]
  node_forum_routes["Forum routes<br/>[forum_topics.go]"]
  node_beatmap_routes["Beatmap routes<br/>[beatmaps.go]"]
  node_ranking_routes["Ranking routes<br/>[rankings_global.go]"]
end

subgraph group_domain["Shared Domain"]
  node_state["Application state<br/>[state.go]"]
  node_repositories["Domain repositories"]
  node_schemas["Domain schemas"]
  node_auth["Authentication"]
  node_performance["Score performance"]
  node_rankings["Ranking services<br/>[service.go]"]
end

subgraph group_jobs["Background Jobs"]
  node_jobs_cli["Jobs command<br/>[main.go]"]
  node_scheduler["Task scheduler<br/>[scheduler.go]"]
  node_tasks["Background tasks"]
end

subgraph group_resources["Resource Delivery"]
  node_resource_resolver["Beatmap resolver"]
  node_storage["Storage interface<br/>[storage.go]"]
  node_local_storage["Local storage<br/>[local.go]"]
  node_s3_storage["S3 storage<br/>[s3.go]"]
end

node_browser(("Browser user"))
node_storage_backend[("Configured storage backend")]

node_browser -->|"sends requests"| node_stern
node_stern -->|"dispatches requests"| node_routes
node_routes -->|"renders pages"| node_templates
node_templates -->|"returns HTML"| node_browser
node_browser -->|"loads scripts"| node_static
node_stern -->|"initializes"| node_state
node_stern -->|"registers service"| node_wiki
node_wiki -->|"reads and writes"| node_repositories
node_wiki -->|"builds records"| node_schemas
node_jobs_cli -->|"initializes"| node_state
node_jobs_cli -->|"runs schedules"| node_scheduler
node_scheduler -->|"dispatches tasks"| node_tasks
node_resource_resolver -->|"reads objects"| node_storage
node_local_storage -.->|"stores objects"| node_storage_backend
node_s3_storage -.->|"stores objects"| node_storage_backend

click node_stern "https://github.com/osutitanic/titanic/blob/main/services/stern/cmd/web/main.go"
click node_routes "https://github.com/osutitanic/titanic/tree/main/services/stern/internal/routes"
click node_templates "https://github.com/osutitanic/titanic/blob/main/services/stern/internal/templates/engine.go"
click node_static "https://github.com/osutitanic/titanic/tree/main/services/stern/web/static/js"
click node_wiki "https://github.com/osutitanic/titanic/blob/main/services/stern/internal/wiki/service.go"
click node_account_routes "https://github.com/osutitanic/titanic/blob/main/services/stern/internal/routes/account_login.go"
click node_forum_routes "https://github.com/osutitanic/titanic/blob/main/services/stern/internal/routes/forum_topics.go"
click node_beatmap_routes "https://github.com/osutitanic/titanic/blob/main/services/stern/internal/routes/beatmaps.go"
click node_ranking_routes "https://github.com/osutitanic/titanic/blob/main/services/stern/internal/routes/rankings_global.go"
click node_state "https://github.com/osutitanic/titanic/blob/main/internal/state/state.go"
click node_repositories "https://github.com/osutitanic/titanic/tree/main/internal/repositories"
click node_schemas "https://github.com/osutitanic/titanic/tree/main/internal/schemas"
click node_auth "https://github.com/osutitanic/titanic/tree/main/internal/authentication"
click node_performance "https://github.com/osutitanic/titanic/tree/main/internal/performance"
click node_rankings "https://github.com/osutitanic/titanic/blob/main/internal/rankings/service.go"
click node_jobs_cli "https://github.com/osutitanic/titanic/blob/main/services/jobs/cmd/cli/main.go"
click node_scheduler "https://github.com/osutitanic/titanic/blob/main/services/jobs/internal/scheduler/scheduler.go"
click node_tasks "https://github.com/osutitanic/titanic/tree/main/services/jobs/internal/tasks"
click node_resource_resolver "https://github.com/osutitanic/titanic/blob/main/internal/resources/provider_storage.go"
click node_storage "https://github.com/osutitanic/titanic/blob/main/internal/storage/storage.go"
click node_local_storage "https://github.com/osutitanic/titanic/blob/main/internal/storage/local.go"
click node_s3_storage "https://github.com/osutitanic/titanic/blob/main/internal/storage/s3.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_stern,node_routes,node_templates,node_static,node_wiki,node_account_routes,node_forum_routes,node_beatmap_routes,node_ranking_routes,node_browser toneBlue
class node_state,node_repositories,node_schemas,node_auth,node_performance,node_rankings,node_storage_backend toneAmber
class node_jobs_cli,node_scheduler,node_tasks toneMint
class node_resource_resolver,node_storage,node_local_storage,node_s3_storage toneRose
```

## Components

### Stern Website

- [Stern HTTP server](https://github.com/osutitanic/titanic/blob/main/services/stern/cmd/web/main.go): `services/stern/cmd/web/main.go`
- [Website routes](https://github.com/osutitanic/titanic/tree/main/services/stern/internal/routes): `services/stern/internal/routes`
- [Page rendering](https://github.com/osutitanic/titanic/blob/main/services/stern/internal/templates/engine.go): `services/stern/internal/templates/engine.go`
- [Browser scripts](https://github.com/osutitanic/titanic/tree/main/services/stern/web/static/js): `services/stern/web/static/js`
- [Wiki service](https://github.com/osutitanic/titanic/blob/main/services/stern/internal/wiki/service.go): `services/stern/internal/wiki/service.go`
- [Account routes](https://github.com/osutitanic/titanic/blob/main/services/stern/internal/routes/account_login.go): `services/stern/internal/routes/account_login.go`
- [Forum routes](https://github.com/osutitanic/titanic/blob/main/services/stern/internal/routes/forum_topics.go): `services/stern/internal/routes/forum_topics.go`
- [Beatmap routes](https://github.com/osutitanic/titanic/blob/main/services/stern/internal/routes/beatmaps.go): `services/stern/internal/routes/beatmaps.go`
- [Ranking routes](https://github.com/osutitanic/titanic/blob/main/services/stern/internal/routes/rankings_global.go): `services/stern/internal/routes/rankings_global.go`

### Shared Domain

- [Application state](https://github.com/osutitanic/titanic/blob/main/internal/state/state.go): `internal/state/state.go`
- [Domain repositories](https://github.com/osutitanic/titanic/tree/main/internal/repositories): `internal/repositories`
- [Domain schemas](https://github.com/osutitanic/titanic/tree/main/internal/schemas): `internal/schemas`
- [Authentication](https://github.com/osutitanic/titanic/tree/main/internal/authentication): `internal/authentication`
- [Score performance](https://github.com/osutitanic/titanic/tree/main/internal/performance): `internal/performance`
- [Ranking services](https://github.com/osutitanic/titanic/blob/main/internal/rankings/service.go): `internal/rankings/service.go`

### Background Jobs

- [Jobs command](https://github.com/osutitanic/titanic/blob/main/services/jobs/cmd/cli/main.go): `services/jobs/cmd/cli/main.go`
- [Task scheduler](https://github.com/osutitanic/titanic/blob/main/services/jobs/internal/scheduler/scheduler.go): `services/jobs/internal/scheduler/scheduler.go`
- [Background tasks](https://github.com/osutitanic/titanic/tree/main/services/jobs/internal/tasks): `services/jobs/internal/tasks`

### Resource Delivery

- [Beatmap resolver](https://github.com/osutitanic/titanic/blob/main/internal/resources/provider_storage.go): `internal/resources/provider_storage.go`
- [Storage interface](https://github.com/osutitanic/titanic/blob/main/internal/storage/storage.go): `internal/storage/storage.go`
- [Local storage](https://github.com/osutitanic/titanic/blob/main/internal/storage/local.go): `internal/storage/local.go`
- [S3 storage](https://github.com/osutitanic/titanic/blob/main/internal/storage/s3.go): `internal/storage/s3.go`

### Other components

- **Browser user**
- **Configured storage backend**

## Connections

- Browser user → Stern HTTP server: sends requests
- Stern HTTP server → Website routes: dispatches requests
- Website routes → Page rendering: renders pages
- Page rendering → Browser user: returns HTML
- Browser user → Browser scripts: loads scripts
- Stern HTTP server → Application state: initializes
- Stern HTTP server → Wiki service: registers service
- Wiki service → Domain repositories: reads and writes
- Wiki service → Domain schemas: builds records
- Jobs command → Application state: initializes
- Jobs command → Task scheduler: runs schedules
- Task scheduler → Background tasks: dispatches tasks
- Beatmap resolver → Storage interface: reads objects
- Local storage → Configured storage backend: stores objects
- S3 storage → Configured storage backend: stores objects