# cooooing/bass architecture

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

- Interactive diagram: https://gitdiagram.com/cooooing/bass
- Repository: https://github.com/cooooing/bass

## Overview

Bass is a Go microservice backend for community and game products. User requests enter through BFFs or domain-service APIs; domain services apply business rules and own their data, while the documented architecture uses gRPC and asynchronous outbox/NATS events for cross-service work. Major product domains in the tree include community content, points economy, idle-game actions and state, and agent-driven town worlds. The sampled platform use case demonstrates object upload/download, metadata persistence, audit, and asset resolution. Source excerpts were limited, so uncertain service-to-service wiring is omitted.

Main entry points: [`app/bff_bbs/internal/service`](https://github.com/cooooing/bass/tree/master/app/bff_bbs/internal/service) (BBS BFF), [`app/platform/internal/biz/usecase/object_storage.go`](https://github.com/cooooing/bass/blob/master/app/platform/internal/biz/usecase/object_storage.go) (Object storage), [`app/content/internal/biz/usecase`](https://github.com/cooooing/bass/tree/master/app/content/internal/biz/usecase) (Content domain), [`common/proto/app/platform/v1/enum/object_storage.proto`](https://github.com/cooooing/bass/blob/master/common/proto/app/platform/v1/enum/object_storage.proto) (Shared contracts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry APIs"]
  node_bbs["BBS BFF"]
  node_idle_bff["Idle BFF"]
  node_http_grpc["HTTP / gRPC APIs"]
end

subgraph group_community["Community Services"]
  node_content["Content domain"]
  node_economy["Points economy"]
end

subgraph group_games["Game Services"]
  node_idle["Idle game"]
  node_town["Game Town"]
  node_town_agent["Town agent runtime"]
end

subgraph group_platform["Platform Services"]
  node_platform_storage["Object storage<br/>[object_storage.go]"]
  node_storage_repo["Storage metadata<br/>[object_storage.go]"]
  node_object_db[("Metadata database<br/>[object_storage.go]")]
  node_storage_client["Storage provider client"]
end

subgraph group_shared["Shared Infrastructure"]
  node_common["Shared contracts"]
  node_nats["NATS events"]
  node_formula["Lua formula engine"]
end

node_client(("Product clients"))
node_blob_provider[("Blob storage")]

node_client -->|"sends requests"| node_bbs
node_client -->|"sends requests"| node_idle_bff
node_client -->|"calls APIs"| node_http_grpc
node_bbs -->|"calls domain APIs"| node_content
node_bbs -->|"calls domain APIs"| node_economy
node_idle_bff -->|"calls game APIs"| node_idle
node_http_grpc -->|"dispatches requests"| node_content
node_town -->|"runs agent jobs"| node_town_agent
node_platform_storage -->|"reads and writes"| node_storage_repo
node_platform_storage -->|"uploads and downloads"| node_storage_client
node_storage_repo -->|"persists metadata"| node_object_db
node_storage_client -->|"transfers objects"| node_blob_provider
node_content -.->|"publishes events"| node_nats
node_common -.->|"defines contracts"| node_bbs
node_common -.->|"defines enums"| node_platform_storage

click node_bbs "https://github.com/cooooing/bass/tree/master/app/bff_bbs/internal/service"
click node_idle_bff "https://github.com/cooooing/bass/tree/master/app/bff_game_idle/internal/service"
click node_content "https://github.com/cooooing/bass/tree/master/app/content/internal/biz/usecase"
click node_economy "https://github.com/cooooing/bass/tree/master/app/economy/internal/biz/usecase"
click node_idle "https://github.com/cooooing/bass/tree/master/app/game_idle/internal/biz/usecase"
click node_town "https://github.com/cooooing/bass/tree/master/app/game_town/internal/biz/usecase"
click node_town_agent "https://github.com/cooooing/bass/blob/master/app/game_town/internal/biz/usecase/world_agent_runner.go"
click node_platform_storage "https://github.com/cooooing/bass/blob/master/app/platform/internal/biz/usecase/object_storage.go"
click node_storage_repo "https://github.com/cooooing/bass/blob/master/app/platform/internal/data/repo/object_storage.go"
click node_object_db "https://github.com/cooooing/bass/blob/master/app/platform/internal/data/schema/object_storage.go"
click node_storage_client "https://github.com/cooooing/bass/blob/master/app/platform/internal/biz/repo/object_storage_client.go"
click node_http_grpc "https://github.com/cooooing/bass/tree/master/app/content/internal/server"
click node_common "https://github.com/cooooing/bass/blob/master/common/proto/app/platform/v1/enum/object_storage.proto"
click node_formula "https://github.com/cooooing/bass/blob/master/common/pkg/util/formula/lua_formula_engine.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_bbs,node_idle_bff,node_http_grpc,node_client toneBlue
class node_content,node_economy,node_blob_provider toneAmber
class node_idle,node_town,node_town_agent toneMint
class node_platform_storage,node_storage_repo,node_object_db,node_storage_client toneRose
class node_common,node_nats,node_formula toneIndigo
```

## Components

### Entry APIs

- [BBS BFF](https://github.com/cooooing/bass/tree/master/app/bff_bbs/internal/service): `app/bff_bbs/internal/service`
- [Idle BFF](https://github.com/cooooing/bass/tree/master/app/bff_game_idle/internal/service): `app/bff_game_idle/internal/service`
- [HTTP / gRPC APIs](https://github.com/cooooing/bass/tree/master/app/content/internal/server): `app/content/internal/server`

### Community Services

- [Content domain](https://github.com/cooooing/bass/tree/master/app/content/internal/biz/usecase): `app/content/internal/biz/usecase`
- [Points economy](https://github.com/cooooing/bass/tree/master/app/economy/internal/biz/usecase): `app/economy/internal/biz/usecase`

### Game Services

- [Idle game](https://github.com/cooooing/bass/tree/master/app/game_idle/internal/biz/usecase): `app/game_idle/internal/biz/usecase`
- [Game Town](https://github.com/cooooing/bass/tree/master/app/game_town/internal/biz/usecase): `app/game_town/internal/biz/usecase`
- [Town agent runtime](https://github.com/cooooing/bass/blob/master/app/game_town/internal/biz/usecase/world_agent_runner.go): `app/game_town/internal/biz/usecase/world_agent_runner.go`

### Platform Services

- [Object storage](https://github.com/cooooing/bass/blob/master/app/platform/internal/biz/usecase/object_storage.go): `app/platform/internal/biz/usecase/object_storage.go`
- [Storage metadata](https://github.com/cooooing/bass/blob/master/app/platform/internal/data/repo/object_storage.go): `app/platform/internal/data/repo/object_storage.go`
- [Metadata database](https://github.com/cooooing/bass/blob/master/app/platform/internal/data/schema/object_storage.go): `app/platform/internal/data/schema/object_storage.go`
- [Storage provider client](https://github.com/cooooing/bass/blob/master/app/platform/internal/biz/repo/object_storage_client.go): `app/platform/internal/biz/repo/object_storage_client.go`

### Shared Infrastructure

- [Shared contracts](https://github.com/cooooing/bass/blob/master/common/proto/app/platform/v1/enum/object_storage.proto): `common/proto/app/platform/v1/enum/object_storage.proto`
- **NATS events**
- [Lua formula engine](https://github.com/cooooing/bass/blob/master/common/pkg/util/formula/lua_formula_engine.go): `common/pkg/util/formula/lua_formula_engine.go`

### Other components

- **Product clients**
- **Blob storage**

## Connections

- Product clients → BBS BFF: sends requests
- Product clients → Idle BFF: sends requests
- Product clients → HTTP / gRPC APIs: calls APIs
- BBS BFF → Content domain: calls domain APIs
- BBS BFF → Points economy: calls domain APIs
- Idle BFF → Idle game: calls game APIs
- HTTP / gRPC APIs → Content domain: dispatches requests
- Game Town → Town agent runtime: runs agent jobs
- Object storage → Storage metadata: reads and writes
- Object storage → Storage provider client: uploads and downloads
- Storage metadata → Metadata database: persists metadata
- Storage provider client → Blob storage: transfers objects
- Content domain → NATS events: publishes events
- Shared contracts → BBS BFF: defines contracts
- Shared contracts → Object storage: defines enums