# mininglamp-oss/octo-server architecture

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

- Interactive diagram: https://gitdiagram.com/mininglamp-oss/octo-server
- Repository: https://github.com/mininglamp-oss/octo-server

## Overview

OCTO Server is the Go backend for OCTO: clients use its REST and WebSocket APIs for workplace, identity, and messaging features, while it coordinates Lobster agents and real-time delivery through WuKongIM. The graph follows the README’s request stages and documented integrations, using paths present in the supplied tree. The README describes some internal layers not present in that tree; their implementation wiring is therefore not inferred from unsampled source.

Main entry points: [`internal/modules.go`](https://github.com/mininglamp-oss/octo-server/blob/main/internal/modules.go) (API modules), [`modules/message`](https://github.com/mininglamp-oss/octo-server/tree/main/modules/message) (Conversations), [`main.go`](https://github.com/mininglamp-oss/octo-server/blob/main/main.go) (Server entry), [`pkg/db/db.go`](https://github.com/mininglamp-oss/octo-server/blob/main/pkg/db/db.go) (SQL storage)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Request entry"]
  node_server["Server entry<br/>[main.go]"]
  node_auth["Authentication<br/>[runtime.go]"]
  node_api["API modules<br/>[modules.go]"]
end

subgraph group_workplace["Workplace features"]
  node_users["Users and roles"]
  node_spaces["Spaces and groups"]
  node_messages["Conversations"]
  node_search["Message search"]
  node_files["File services"]
end

subgraph group_agents["Agents and integrations"]
  node_agents["Agent orchestration<br/>[service.go]"]
  node_botapi["Bot APIs"]
  node_webhooks["Webhook adapters"]
end

subgraph group_runtime["Runtime services"]
  node_sql[("SQL storage<br/>[db.go]")]
  node_redis[("Redis storage<br/>[redis.go]")]
  node_im["WuKongIM"]
end

node_web(("Web client"))
node_admin(("Admin client"))
node_lobster(("Lobster agents"))
node_adapters["External bridges"]

node_web -->|"REST / WebSocket"| node_server
node_admin -->|"REST / WebSocket"| node_server
node_server -->|"authenticate"| node_auth
node_server -->|"dispatch requests"| node_api
node_api -->|"handle identity"| node_users
node_api -->|"handle membership"| node_spaces
node_api -->|"handle conversations"| node_messages
node_api -->|"handle search"| node_search
node_api -->|"handle files"| node_files
node_api -->|"coordinate agents"| node_agents
node_api -->|"serve bot requests"| node_botapi
node_api -->|"dispatch webhooks"| node_webhooks
node_agents -->|"schedule sessions"| node_lobster
node_webhooks -->|"bridge events"| node_adapters
node_messages -->|"fan out messages"| node_im
node_users -->|"read / write"| node_sql
node_spaces -->|"read / write"| node_sql
node_messages -->|"read / write"| node_sql
node_messages -->|"use cache"| node_redis
node_files -.->|"use object storage"| node_adapters

click node_server "https://github.com/mininglamp-oss/octo-server/blob/main/main.go"
click node_auth "https://github.com/mininglamp-oss/octo-server/blob/main/pkg/auth/runtime.go"
click node_api "https://github.com/mininglamp-oss/octo-server/blob/main/internal/modules.go"
click node_users "https://github.com/mininglamp-oss/octo-server/tree/main/modules/user"
click node_spaces "https://github.com/mininglamp-oss/octo-server/tree/main/modules/space"
click node_messages "https://github.com/mininglamp-oss/octo-server/tree/main/modules/message"
click node_search "https://github.com/mininglamp-oss/octo-server/tree/main/modules/messages_search"
click node_files "https://github.com/mininglamp-oss/octo-server/tree/main/modules/file"
click node_agents "https://github.com/mininglamp-oss/octo-server/blob/main/modules/ai_team/service.go"
click node_botapi "https://github.com/mininglamp-oss/octo-server/tree/main/modules/bot_api"
click node_webhooks "https://github.com/mininglamp-oss/octo-server/tree/main/modules/incomingwebhook"
click node_sql "https://github.com/mininglamp-oss/octo-server/blob/main/pkg/db/db.go"
click node_redis "https://github.com/mininglamp-oss/octo-server/blob/main/pkg/db/redis.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_server,node_auth,node_api,node_web,node_admin toneBlue
class node_users,node_spaces,node_messages,node_search,node_files toneAmber
class node_agents,node_botapi,node_webhooks toneMint
class node_sql,node_redis,node_im toneRose
class node_lobster,node_adapters toneIndigo
```

## Components

### Request entry

- [Server entry](https://github.com/mininglamp-oss/octo-server/blob/main/main.go): `main.go`
- [Authentication](https://github.com/mininglamp-oss/octo-server/blob/main/pkg/auth/runtime.go): `pkg/auth/runtime.go`
- [API modules](https://github.com/mininglamp-oss/octo-server/blob/main/internal/modules.go): `internal/modules.go`

### Workplace features

- [Users and roles](https://github.com/mininglamp-oss/octo-server/tree/main/modules/user): `modules/user`
- [Spaces and groups](https://github.com/mininglamp-oss/octo-server/tree/main/modules/space): `modules/space`
- [Conversations](https://github.com/mininglamp-oss/octo-server/tree/main/modules/message): `modules/message`
- [Message search](https://github.com/mininglamp-oss/octo-server/tree/main/modules/messages_search): `modules/messages_search`
- [File services](https://github.com/mininglamp-oss/octo-server/tree/main/modules/file): `modules/file`

### Agents and integrations

- [Agent orchestration](https://github.com/mininglamp-oss/octo-server/blob/main/modules/ai_team/service.go): `modules/ai_team/service.go`
- [Bot APIs](https://github.com/mininglamp-oss/octo-server/tree/main/modules/bot_api): `modules/bot_api`
- [Webhook adapters](https://github.com/mininglamp-oss/octo-server/tree/main/modules/incomingwebhook): `modules/incomingwebhook`

### Runtime services

- [SQL storage](https://github.com/mininglamp-oss/octo-server/blob/main/pkg/db/db.go): `pkg/db/db.go`
- [Redis storage](https://github.com/mininglamp-oss/octo-server/blob/main/pkg/db/redis.go): `pkg/db/redis.go`
- **WuKongIM**

### Other components

- **Web client**
- **Admin client**
- **Lobster agents**
- **External bridges**

## Connections

- Web client → Server entry: REST / WebSocket
- Admin client → Server entry: REST / WebSocket
- Server entry → Authentication: authenticate
- Server entry → API modules: dispatch requests
- API modules → Users and roles: handle identity
- API modules → Spaces and groups: handle membership
- API modules → Conversations: handle conversations
- API modules → Message search: handle search
- API modules → File services: handle files
- API modules → Agent orchestration: coordinate agents
- API modules → Bot APIs: serve bot requests
- API modules → Webhook adapters: dispatch webhooks
- Agent orchestration → Lobster agents: schedule sessions
- Webhook adapters → External bridges: bridge events
- Conversations → WuKongIM: fan out messages
- Users and roles → SQL storage: read / write
- Spaces and groups → SQL storage: read / write
- Conversations → SQL storage: read / write
- Conversations → Redis storage: use cache
- File services → External bridges: use object storage