# tqk114514/nebulastudios-website architecture

> Architecture diagram of the GitHub repository tqk114514/nebulastudios-website, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/tqk114514/nebulastudios-website
- Repository: https://github.com/tqk114514/nebulastudios-website

## Overview

Nebula Studios is a website and account platform: users register or sign in, complete verification and optional TOTP, manage profiles and consent, and can authorize third-party OAuth clients. Administrators manage users, OAuth clients, email-domain allowlists, logs, and data transfers. The Vue SPA calls Go/Gin APIs backed by PostgreSQL and services; avatar uploads are converted to WebP by the separate image processor and stored locally. The README also documents Microsoft/Google sign-in, internationalized policy pages, CAPTCHA, rate limiting, and diagnostics. Arrows are limited to relationships shown in excerpts or explicitly documented; unsampled feature internals are represented at their tree paths.

Main entry points: [`cmd/server/routes.go`](https://github.com/tqk114514/nebulastudios-website/blob/main/cmd/server/routes.go) (HTTP routes), [`internal/handlers/auth/handler.go`](https://github.com/tqk114514/nebulastudios-website/blob/main/internal/handlers/auth/handler.go) (Authentication), [`cmd/server/main.go`](https://github.com/tqk114514/nebulastudios-website/blob/main/cmd/server/main.go) (Go HTTP server), [`frontend/src/App.vue`](https://github.com/tqk114514/nebulastudios-website/blob/main/frontend/src/App.vue) (Vue application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web experience"]
  node_spa["Vue application<br/>[App.vue]"]
  node_router["Page routing<br/>[index.ts]"]
  node_pages["Product pages"]
  node_localization["Localization<br/>[index.ts]"]
  node_api_client["API client<br/>[client.ts]"]
  node_policy["Policy and consent<br/>[policy.go]"]
end

subgraph group_identity["Identity and accounts"]
  node_auth_ui["Account flows"]
  node_user_handlers["Account handlers"]
  node_auth_handler["Authentication<br/>[handler.go]"]
  node_totp["Two-step verification<br/>[totp.go]"]
  node_oauth_provider["OAuth provider<br/>[provider.go]"]
  node_external_oauth["Google and Microsoft"]
  node_google_proxy["Google proxy"]
  node_sessions["Session service<br/>[session.go]"]
end

subgraph group_admin["Administration"]
  node_oauth_client_ui["OAuth client console"]
  node_admin_ui["Admin console"]
  node_admin_handlers["Admin operations"]
  node_exports["Data export<br/>[export.go]"]
end

subgraph group_platform["Platform services"]
  node_captcha["CAPTCHA verification<br/>[captcha.go]"]
  node_rate_limit["Rate limiting<br/>[ratelimit.go]"]
  node_email["Email delivery<br/>[email.go]"]
  node_user_cache["User cache<br/>[user.go]"]
  node_server["Go HTTP server<br/>[main.go]"]
  node_routes["HTTP routes<br/>[routes.go]"]
  node_background_tasks["Background tasks<br/>[tasks.go]"]
  node_static["Static and avatar routes<br/>[static.go]"]
  node_pprof["Diagnostics<br/>[pprof.go]"]
end

subgraph group_storage["Persistence and media"]
  node_postgres[("PostgreSQL models")]
  node_avatar_storage["Avatar storage<br/>[localstorage.go]"]
  node_image_processor["Image processor<br/>[stb_impl.c]"]
end

node_visitor(("Visitor"))
node_turnstile(("Cloudflare Turnstile"))
node_microsoft_google(("Microsoft / Google"))
node_smtp(("SMTP server"))

node_visitor -->|"opens"| node_spa
node_spa -->|"renders routes"| node_router
node_router -->|"selects pages"| node_pages
node_spa -->|"uses translations"| node_localization
node_pages -.->|"calls API"| node_api_client
node_auth_ui -->|"calls API"| node_api_client
node_visitor -->|"registers or signs in"| node_auth_ui
node_auth_handler -->|"verifies TOTP"| node_totp
node_auth_handler -->|"refreshes tokens"| node_sessions
node_routes -->|"routes auth"| node_auth_handler
node_routes -.->|"routes accounts"| node_user_handlers
node_routes -->|"routes admin"| node_admin_handlers
node_routes -->|"routes OAuth"| node_oauth_provider
node_routes -->|"routes sign-in"| node_external_oauth
node_external_oauth -->|"exchanges identity"| node_microsoft_google
node_google_proxy -->|"proxies Google API"| node_microsoft_google
node_visitor -->|"manages clients"| node_oauth_client_ui
node_oauth_client_ui -->|"requests admin API"| node_api_client
node_oauth_client_ui -->|"uses pagination"| node_admin_ui
node_admin_handlers -.->|"reads and writes"| node_postgres
node_oauth_provider -->|"stores client tokens"| node_postgres
node_auth_handler -.->|"reads and writes accounts"| node_postgres
node_auth_handler -.->|"sends verification mail"| node_email
node_email -->|"delivers mail"| node_smtp
node_auth_handler -.->|"checks challenges"| node_captcha
node_captcha -->|"validates challenge"| node_turnstile
node_routes -->|"applies limits"| node_rate_limit
node_admin_handlers -.->|"exports data"| node_exports
node_auth_handler -.->|"uses cache"| node_user_cache
node_user_handlers -.->|"stores avatars"| node_avatar_storage
node_avatar_storage -->|"converts images"| node_image_processor
node_avatar_storage -.->|"serves stored avatars"| node_static
node_routes -->|"routes avatars"| node_static
node_server -.->|"configures routes"| node_routes
node_server -->|"starts tasks"| node_background_tasks
node_server -.->|"starts diagnostics"| node_pprof
node_visitor -->|"views policies"| node_policy

click node_spa "https://github.com/tqk114514/nebulastudios-website/blob/main/frontend/src/App.vue"
click node_router "https://github.com/tqk114514/nebulastudios-website/blob/main/frontend/src/router/index.ts"
click node_pages "https://github.com/tqk114514/nebulastudios-website/tree/main/frontend/src/pages"
click node_localization "https://github.com/tqk114514/nebulastudios-website/blob/main/frontend/src/i18n/index.ts"
click node_api_client "https://github.com/tqk114514/nebulastudios-website/blob/main/frontend/src/api/client.ts"
click node_auth_ui "https://github.com/tqk114514/nebulastudios-website/tree/main/frontend/src/pages/account"
click node_user_handlers "https://github.com/tqk114514/nebulastudios-website/tree/main/internal/handlers/user"
click node_auth_handler "https://github.com/tqk114514/nebulastudios-website/blob/main/internal/handlers/auth/handler.go"
click node_totp "https://github.com/tqk114514/nebulastudios-website/blob/main/internal/services/totp.go"
click node_oauth_client_ui "https://github.com/tqk114514/nebulastudios-website/blob/main/frontend/src/pages/admin/OAuthClientsPage.vue"
click node_admin_ui "https://github.com/tqk114514/nebulastudios-website/tree/main/frontend/src/pages/admin"
click node_admin_handlers "https://github.com/tqk114514/nebulastudios-website/tree/main/internal/handlers/admin"
click node_oauth_provider "https://github.com/tqk114514/nebulastudios-website/blob/main/internal/handlers/oauth/provider.go"
click node_external_oauth "https://github.com/tqk114514/nebulastudios-website/tree/main/internal/handlers/oauth"
click node_google_proxy "https://github.com/tqk114514/nebulastudios-website/blob/main/google-oauth-proxy.js"
click node_policy "https://github.com/tqk114514/nebulastudios-website/blob/main/internal/handlers/policy.go"
click node_captcha "https://github.com/tqk114514/nebulastudios-website/blob/main/internal/services/captcha.go"
click node_rate_limit "https://github.com/tqk114514/nebulastudios-website/blob/main/internal/middleware/ratelimit.go"
click node_sessions "https://github.com/tqk114514/nebulastudios-website/blob/main/internal/services/session.go"
click node_email "https://github.com/tqk114514/nebulastudios-website/blob/main/internal/services/email.go"
click node_exports "https://github.com/tqk114514/nebulastudios-website/blob/main/internal/services/export.go"
click node_user_cache "https://github.com/tqk114514/nebulastudios-website/blob/main/internal/cache/user.go"
click node_postgres "https://github.com/tqk114514/nebulastudios-website/tree/main/internal/models"
click node_avatar_storage "https://github.com/tqk114514/nebulastudios-website/blob/main/internal/services/localstorage.go"
click node_image_processor "https://github.com/tqk114514/nebulastudios-website/blob/main/img-processor/src/stb_impl.c"
click node_server "https://github.com/tqk114514/nebulastudios-website/blob/main/cmd/server/main.go"
click node_routes "https://github.com/tqk114514/nebulastudios-website/blob/main/cmd/server/routes.go"
click node_background_tasks "https://github.com/tqk114514/nebulastudios-website/blob/main/cmd/server/tasks.go"
click node_static "https://github.com/tqk114514/nebulastudios-website/blob/main/internal/handlers/static.go"
click node_pprof "https://github.com/tqk114514/nebulastudios-website/blob/main/cmd/server/pprof.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_spa,node_router,node_pages,node_localization,node_api_client,node_policy toneBlue
class node_auth_ui,node_user_handlers,node_auth_handler,node_totp,node_oauth_provider,node_external_oauth,node_google_proxy,node_sessions toneAmber
class node_oauth_client_ui,node_admin_ui,node_admin_handlers,node_exports,node_smtp toneMint
class node_captcha,node_rate_limit,node_email,node_user_cache,node_server,node_routes,node_background_tasks,node_static,node_pprof toneRose
class node_postgres,node_avatar_storage,node_image_processor,node_visitor,node_turnstile,node_microsoft_google toneIndigo
```

## Components

### Web experience

- [Vue application](https://github.com/tqk114514/nebulastudios-website/blob/main/frontend/src/App.vue): `frontend/src/App.vue`
- [Page routing](https://github.com/tqk114514/nebulastudios-website/blob/main/frontend/src/router/index.ts): `frontend/src/router/index.ts`
- [Product pages](https://github.com/tqk114514/nebulastudios-website/tree/main/frontend/src/pages): `frontend/src/pages`
- [Localization](https://github.com/tqk114514/nebulastudios-website/blob/main/frontend/src/i18n/index.ts): `frontend/src/i18n/index.ts`
- [API client](https://github.com/tqk114514/nebulastudios-website/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Policy and consent](https://github.com/tqk114514/nebulastudios-website/blob/main/internal/handlers/policy.go): `internal/handlers/policy.go`

### Identity and accounts

- [Account flows](https://github.com/tqk114514/nebulastudios-website/tree/main/frontend/src/pages/account): `frontend/src/pages/account`
- [Account handlers](https://github.com/tqk114514/nebulastudios-website/tree/main/internal/handlers/user): `internal/handlers/user`
- [Authentication](https://github.com/tqk114514/nebulastudios-website/blob/main/internal/handlers/auth/handler.go): `internal/handlers/auth/handler.go`
- [Two-step verification](https://github.com/tqk114514/nebulastudios-website/blob/main/internal/services/totp.go): `internal/services/totp.go`
- [OAuth provider](https://github.com/tqk114514/nebulastudios-website/blob/main/internal/handlers/oauth/provider.go): `internal/handlers/oauth/provider.go`
- [Google and Microsoft](https://github.com/tqk114514/nebulastudios-website/tree/main/internal/handlers/oauth): `internal/handlers/oauth`
- [Google proxy](https://github.com/tqk114514/nebulastudios-website/blob/main/google-oauth-proxy.js): `google-oauth-proxy.js`
- [Session service](https://github.com/tqk114514/nebulastudios-website/blob/main/internal/services/session.go): `internal/services/session.go`

### Administration

- [OAuth client console](https://github.com/tqk114514/nebulastudios-website/blob/main/frontend/src/pages/admin/OAuthClientsPage.vue): `frontend/src/pages/admin/OAuthClientsPage.vue`
- [Admin console](https://github.com/tqk114514/nebulastudios-website/tree/main/frontend/src/pages/admin): `frontend/src/pages/admin`
- [Admin operations](https://github.com/tqk114514/nebulastudios-website/tree/main/internal/handlers/admin): `internal/handlers/admin`
- [Data export](https://github.com/tqk114514/nebulastudios-website/blob/main/internal/services/export.go): `internal/services/export.go`

### Platform services

- [CAPTCHA verification](https://github.com/tqk114514/nebulastudios-website/blob/main/internal/services/captcha.go): `internal/services/captcha.go`
- [Rate limiting](https://github.com/tqk114514/nebulastudios-website/blob/main/internal/middleware/ratelimit.go): `internal/middleware/ratelimit.go`
- [Email delivery](https://github.com/tqk114514/nebulastudios-website/blob/main/internal/services/email.go): `internal/services/email.go`
- [User cache](https://github.com/tqk114514/nebulastudios-website/blob/main/internal/cache/user.go): `internal/cache/user.go`
- [Go HTTP server](https://github.com/tqk114514/nebulastudios-website/blob/main/cmd/server/main.go): `cmd/server/main.go`
- [HTTP routes](https://github.com/tqk114514/nebulastudios-website/blob/main/cmd/server/routes.go): `cmd/server/routes.go`
- [Background tasks](https://github.com/tqk114514/nebulastudios-website/blob/main/cmd/server/tasks.go): `cmd/server/tasks.go`
- [Static and avatar routes](https://github.com/tqk114514/nebulastudios-website/blob/main/internal/handlers/static.go): `internal/handlers/static.go`
- [Diagnostics](https://github.com/tqk114514/nebulastudios-website/blob/main/cmd/server/pprof.go): `cmd/server/pprof.go`

### Persistence and media

- [PostgreSQL models](https://github.com/tqk114514/nebulastudios-website/tree/main/internal/models): `internal/models`
- [Avatar storage](https://github.com/tqk114514/nebulastudios-website/blob/main/internal/services/localstorage.go): `internal/services/localstorage.go`
- [Image processor](https://github.com/tqk114514/nebulastudios-website/blob/main/img-processor/src/stb_impl.c): `img-processor/src/stb_impl.c`

### Other components

- **Visitor**
- **Cloudflare Turnstile**
- **Microsoft / Google**
- **SMTP server**

## Connections

- Visitor → Vue application: opens
- Vue application → Page routing: renders routes (evidence: `frontend/src/App.vue`)
- Page routing → Product pages: selects pages
- Vue application → Localization: uses translations
- Product pages → API client: calls API
- Account flows → API client: calls API (evidence: `frontend/src/api/client.ts`)
- Visitor → Account flows: registers or signs in
- Authentication → Two-step verification: verifies TOTP (evidence: `internal/handlers/auth/handler.go`)
- Authentication → Session service: refreshes tokens (evidence: `internal/handlers/auth/handler.go`)
- HTTP routes → Authentication: routes auth (evidence: `cmd/server/routes.go`)
- HTTP routes → Account handlers: routes accounts
- HTTP routes → Admin operations: routes admin (evidence: `cmd/server/routes.go`)
- HTTP routes → OAuth provider: routes OAuth (evidence: `cmd/server/routes.go`)
- HTTP routes → Google and Microsoft: routes sign-in (evidence: `cmd/server/routes.go`)
- Google and Microsoft → Microsoft / Google: exchanges identity
- Google proxy → Microsoft / Google: proxies Google API
- Visitor → OAuth client console: manages clients
- OAuth client console → API client: requests admin API (evidence: `frontend/src/pages/admin/OAuthClientsPage.vue`)
- OAuth client console → Admin console: uses pagination (evidence: `frontend/src/pages/admin/OAuthClientsPage.vue`)
- Admin operations → PostgreSQL models: reads and writes
- OAuth provider → PostgreSQL models: stores client tokens
- Authentication → PostgreSQL models: reads and writes accounts
- Authentication → Email delivery: sends verification mail
- Email delivery → SMTP server: delivers mail
- Authentication → CAPTCHA verification: checks challenges
- CAPTCHA verification → Cloudflare Turnstile: validates challenge
- HTTP routes → Rate limiting: applies limits (evidence: `cmd/server/routes.go`)
- Admin operations → Data export: exports data
- Authentication → User cache: uses cache
- Account handlers → Avatar storage: stores avatars
- Avatar storage → Image processor: converts images (evidence: `internal/services/localstorage.go`)
- Avatar storage → Static and avatar routes: serves stored avatars
- HTTP routes → Static and avatar routes: routes avatars (evidence: `cmd/server/routes.go`)
- Go HTTP server → HTTP routes: configures routes
- Go HTTP server → Background tasks: starts tasks (evidence: `cmd/server/tasks.go`)
- Go HTTP server → Diagnostics: starts diagnostics
- Visitor → Policy and consent: views policies
