# xinrea/joiask architecture

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

## Overview

JoiAsk is a public question-box product with a separate administration interface and Go API. The main flow is visitors browsing or submitting tagged questions, optionally with images; administrators manage questions and site settings. Supporting branches include member registration through Bilibili follow verification, live question updates, and image storage. The graph uses documented routes and sampled controller behavior; frontend-to-API links reflect the documented API boundary, while uncertain internal wiring is omitted.

Main entry points: [`internal/router/router.go`](https://github.com/xinrea/joiask/blob/main/internal/router/router.go) (API router), [`internal/database/database.go`](https://github.com/xinrea/joiask/blob/main/internal/database/database.go) (Application database), [`internal/controller/question_controller.go`](https://github.com/xinrea/joiask/blob/main/internal/controller/question_controller.go) (Question workflows), [`frontend/src/lib/api.ts`](https://github.com/xinrea/joiask/blob/main/frontend/src/lib/api.ts) (Web API client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_public_site["Question site<br/>[page.tsx]"]
  node_discovery["Search and tags<br/>[page.tsx]"]
  node_admin_site["Admin dashboard<br/>[page.tsx]"]
  node_frontend_api["Web API client<br/>[api.ts]"]
  node_live_updates["Live updates<br/>[useWebSocket.ts]"]
end

subgraph group_api["API and workflows"]
  node_router["API router<br/>[router.go]"]
  node_questions["Question workflows"]
  node_tags["Tag management<br/>[tag_controller.go]"]
  node_site_settings["Site settings"]
  node_admin_members["Member management"]
end

subgraph group_identity["Accounts and verification"]
  node_account["Member accounts"]
  node_verification_account["Verification setup"]
  node_verification_worker["Follow verification<br/>[worker.go]"]
  node_bilibili_client["Bilibili client<br/>[client.go]"]
end

subgraph group_state["Persistence and integrations"]
  node_database[("Application database<br/>[database.go]")]
  node_image_storage["Image storage selector<br/>[storage.go]"]
  node_local_storage["Local storage<br/>[local.go]"]
  node_oss_storage["OSS storage<br/>[oss.go]"]
end

node_visitor(("Visitor"))
node_administrator(("Administrator"))
node_bilibili_service{{"Bilibili service"}}

node_visitor -->|"browses and submits"| node_public_site
node_visitor -->|"searches and filters"| node_discovery
node_administrator -->|"manages site"| node_admin_site
node_public_site -->|"requests data"| node_frontend_api
node_discovery -->|"requests results"| node_frontend_api
node_admin_site -->|"requests changes"| node_frontend_api
node_frontend_api -->|"calls API"| node_router
node_router -->|"dispatches questions"| node_questions
node_router -->|"dispatches tags"| node_tags
node_router -->|"dispatches settings"| node_site_settings
node_router -->|"dispatches accounts"| node_account
node_router -->|"dispatches verification setup"| node_verification_account
node_router -->|"dispatches members"| node_admin_members
node_questions -->|"reads and writes"| node_database
node_tags -->|"reads and writes"| node_database
node_site_settings -->|"reads and writes"| node_database
node_account -->|"reads and writes"| node_database
node_admin_members -->|"reads and writes"| node_database
node_questions -->|"uploads and deletes"| node_image_storage
node_image_storage -.->|"selects local"| node_local_storage
node_image_storage -.->|"selects OSS"| node_oss_storage
node_questions -->|"broadcasts updates"| node_live_updates
node_verification_account -->|"validates account"| node_bilibili_client
node_verification_worker -->|"loads and updates"| node_database
node_verification_worker -->|"checks followers"| node_bilibili_client
node_bilibili_client -->|"requests account data"| node_bilibili_service
node_admin_members -->|"fetches profiles"| node_bilibili_client

click node_public_site "https://github.com/xinrea/joiask/blob/main/frontend/src/app/page.tsx"
click node_discovery "https://github.com/xinrea/joiask/blob/main/frontend/src/app/search/page.tsx"
click node_admin_site "https://github.com/xinrea/joiask/blob/main/admin/src/app/dashboard/page.tsx"
click node_frontend_api "https://github.com/xinrea/joiask/blob/main/frontend/src/lib/api.ts"
click node_live_updates "https://github.com/xinrea/joiask/blob/main/frontend/src/hooks/useWebSocket.ts"
click node_router "https://github.com/xinrea/joiask/blob/main/internal/router/router.go"
click node_questions "https://github.com/xinrea/joiask/blob/main/internal/controller/question_controller.go"
click node_tags "https://github.com/xinrea/joiask/blob/main/internal/controller/tag_controller.go"
click node_site_settings "https://github.com/xinrea/joiask/blob/main/internal/controller/config_controller.go"
click node_admin_members "https://github.com/xinrea/joiask/blob/main/internal/controller/member_controller.go"
click node_account "https://github.com/xinrea/joiask/blob/main/internal/controller/account_controller.go"
click node_verification_account "https://github.com/xinrea/joiask/blob/main/internal/controller/bilibili_verification_account_controller.go"
click node_verification_worker "https://github.com/xinrea/joiask/blob/main/internal/verification/worker.go"
click node_bilibili_client "https://github.com/xinrea/joiask/blob/main/internal/bilibili/client.go"
click node_database "https://github.com/xinrea/joiask/blob/main/internal/database/database.go"
click node_image_storage "https://github.com/xinrea/joiask/blob/main/internal/storage/storage.go"
click node_local_storage "https://github.com/xinrea/joiask/blob/main/internal/storage/local.go"
click node_oss_storage "https://github.com/xinrea/joiask/blob/main/internal/storage/oss.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_public_site,node_discovery,node_admin_site,node_frontend_api,node_live_updates toneBlue
class node_router,node_questions,node_tags,node_site_settings,node_admin_members toneAmber
class node_account,node_verification_account,node_verification_worker,node_bilibili_client toneMint
class node_database,node_image_storage,node_local_storage,node_oss_storage toneRose
class node_visitor,node_administrator,node_bilibili_service toneIndigo
```

## Components

### Web experience

- [Question site](https://github.com/xinrea/joiask/blob/main/frontend/src/app/page.tsx): `frontend/src/app/page.tsx`
- [Search and tags](https://github.com/xinrea/joiask/blob/main/frontend/src/app/search/page.tsx): `frontend/src/app/search/page.tsx`
- [Admin dashboard](https://github.com/xinrea/joiask/blob/main/admin/src/app/dashboard/page.tsx): `admin/src/app/dashboard/page.tsx`
- [Web API client](https://github.com/xinrea/joiask/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`
- [Live updates](https://github.com/xinrea/joiask/blob/main/frontend/src/hooks/useWebSocket.ts): `frontend/src/hooks/useWebSocket.ts`

### API and workflows

- [API router](https://github.com/xinrea/joiask/blob/main/internal/router/router.go): `internal/router/router.go`
- [Question workflows](https://github.com/xinrea/joiask/blob/main/internal/controller/question_controller.go): `internal/controller/question_controller.go`
- [Tag management](https://github.com/xinrea/joiask/blob/main/internal/controller/tag_controller.go): `internal/controller/tag_controller.go`
- [Site settings](https://github.com/xinrea/joiask/blob/main/internal/controller/config_controller.go): `internal/controller/config_controller.go`
- [Member management](https://github.com/xinrea/joiask/blob/main/internal/controller/member_controller.go): `internal/controller/member_controller.go`

### Accounts and verification

- [Member accounts](https://github.com/xinrea/joiask/blob/main/internal/controller/account_controller.go): `internal/controller/account_controller.go`
- [Verification setup](https://github.com/xinrea/joiask/blob/main/internal/controller/bilibili_verification_account_controller.go): `internal/controller/bilibili_verification_account_controller.go`
- [Follow verification](https://github.com/xinrea/joiask/blob/main/internal/verification/worker.go): `internal/verification/worker.go`
- [Bilibili client](https://github.com/xinrea/joiask/blob/main/internal/bilibili/client.go): `internal/bilibili/client.go`

### Persistence and integrations

- [Application database](https://github.com/xinrea/joiask/blob/main/internal/database/database.go): `internal/database/database.go`
- [Image storage selector](https://github.com/xinrea/joiask/blob/main/internal/storage/storage.go): `internal/storage/storage.go`
- [Local storage](https://github.com/xinrea/joiask/blob/main/internal/storage/local.go): `internal/storage/local.go`
- [OSS storage](https://github.com/xinrea/joiask/blob/main/internal/storage/oss.go): `internal/storage/oss.go`

### Other components

- **Visitor**
- **Administrator**
- **Bilibili service**

## Connections

- Visitor → Question site: browses and submits
- Visitor → Search and tags: searches and filters
- Administrator → Admin dashboard: manages site
- Question site → Web API client: requests data
- Search and tags → Web API client: requests results
- Admin dashboard → Web API client: requests changes
- Web API client → API router: calls API
- API router → Question workflows: dispatches questions
- API router → Tag management: dispatches tags
- API router → Site settings: dispatches settings
- API router → Member accounts: dispatches accounts
- API router → Verification setup: dispatches verification setup
- API router → Member management: dispatches members
- Question workflows → Application database: reads and writes
- Tag management → Application database: reads and writes
- Site settings → Application database: reads and writes
- Member accounts → Application database: reads and writes
- Member management → Application database: reads and writes
- Question workflows → Image storage selector: uploads and deletes
- Image storage selector → Local storage: selects local
- Image storage selector → OSS storage: selects OSS
- Question workflows → Live updates: broadcasts updates
- Verification setup → Bilibili client: validates account
- Follow verification → Application database: loads and updates
- Follow verification → Bilibili client: checks followers
- Bilibili client → Bilibili service: requests account data
- Member management → Bilibili client: fetches profiles