# mk6i/open-oscar-server architecture

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

- Interactive diagram: https://gitdiagram.com/mk6i/open-oscar-server
- Repository: https://github.com/mk6i/open-oscar-server

## Overview

Open OSCAR Server is a Go instant-messaging server for classic AIM and ICQ clients. Its main workflow accepts client connections through OSCAR-compatible transports, dispatches protocol requests to handlers and domain services, and maintains user, session, buddy-list, and chat state. Separate front ends support TOC, ICQ’s legacy UDP protocol, and AIM’s Web API; an HTTP Management API administers users, sessions, and public chat rooms. The README documents additional messaging, presence, privacy, directory, and file-sharing capabilities. Edges reflect shown calls or README statements; unsampled subsystem links are omitted rather than inferred.

Main entry points: [`cmd/server/main.go`](https://github.com/mk6i/open-oscar-server/blob/main/cmd/server/main.go) (Server process), [`foodgroup/feedbag.go`](https://github.com/mk6i/open-oscar-server/blob/main/foodgroup/feedbag.go) (Buddy lists), [`server/oscar/handler.go`](https://github.com/mk6i/open-oscar-server/blob/main/server/oscar/handler.go) (OSCAR handlers), [`server/icq_legacy/server.go`](https://github.com/mk6i/open-oscar-server/blob/main/server/icq_legacy/server.go) (Legacy ICQ UDP)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Server entry and transports"]
  node_main["Server process<br/>[main.go]"]
  node_oscar["OSCAR transport<br/>[server.go]"]
  node_toc["TOC transport<br/>[server.go]"]
  node_legacy["Legacy ICQ UDP<br/>[server.go]"]
end

subgraph group_protocol["Protocol handling"]
  node_oscarhandler["OSCAR handlers<br/>[handler.go]"]
  node_toccommands["TOC commands<br/>[cmd_client.go]"]
  node_legacyservice["Legacy ICQ service<br/>[service.go]"]
  node_wire["Wire protocol<br/>[snacs.go]"]
end

subgraph group_services["Messaging services"]
  node_auth["Authentication<br/>[auth.go]"]
  node_feedbag["Buddy lists<br/>[feedbag.go]"]
  node_icqservices["ICQ services<br/>[icq.go]"]
  node_oservices["Session services<br/>[oservice.go]"]
end

subgraph group_state["Runtime state"]
  node_session["User sessions<br/>[session.go]"]
  node_sessionmanager["Session registry<br/>[session_manager.go]"]
  node_users[("User accounts<br/>[user_store.go]")]
  node_chatstate["Chat state<br/>[chat.go]"]
  node_buddyfeedstate["Buddy-list state<br/>[feedbag_list.go]"]
end

subgraph group_http["HTTP APIs"]
  node_webapi["AIM Web API<br/>[server.go]"]
  node_webauth["Web authentication<br/>[auth_handler.go]"]
  node_buddymanager["Web buddy lists"]
  node_mgmt["Management API<br/>[mgmt_api.go]"]
end

node_client(("AIM / ICQ clients"))
node_admin(("Server administrators"))

node_client -->|"connects"| node_oscar
node_client -->|"connects"| node_toc
node_client -->|"connects"| node_legacy
node_main -->|"starts"| node_oscar
node_main -->|"starts"| node_toc
node_main -->|"starts"| node_mgmt
node_main -->|"starts"| node_webapi
node_main -->|"starts"| node_legacy
node_oscarhandler -->|"calls"| node_feedbag
node_oscarhandler -.->|"calls"| node_auth
node_toccommands -->|"calls"| node_oservices
node_toccommands -->|"calls"| node_feedbag
node_buddymanager -->|"queries"| node_feedbag
node_oservices -.->|"updates"| node_session
node_sessionmanager -->|"relays"| node_session
node_admin -->|"administers"| node_mgmt
node_client -->|"uses"| node_webapi
node_webapi -.->|"routes"| node_webauth
node_legacy -->|"dispatches"| node_legacyservice
node_client -.->|"uses"| node_icqservices
node_wire -.->|"encodes frames"| node_oscarhandler
node_users -.->|"supports"| node_session
node_feedbag -.->|"updates"| node_buddyfeedstate
node_chatstate -.->|"tracks participants"| node_sessionmanager

click node_main "https://github.com/mk6i/open-oscar-server/blob/main/cmd/server/main.go"
click node_oscar "https://github.com/mk6i/open-oscar-server/blob/main/server/oscar/server.go"
click node_toc "https://github.com/mk6i/open-oscar-server/blob/main/server/toc/server.go"
click node_legacy "https://github.com/mk6i/open-oscar-server/blob/main/server/icq_legacy/server.go"
click node_oscarhandler "https://github.com/mk6i/open-oscar-server/blob/main/server/oscar/handler.go"
click node_toccommands "https://github.com/mk6i/open-oscar-server/blob/main/server/toc/cmd_client.go"
click node_legacyservice "https://github.com/mk6i/open-oscar-server/blob/main/server/icq_legacy/service.go"
click node_wire "https://github.com/mk6i/open-oscar-server/blob/main/wire/snacs.go"
click node_auth "https://github.com/mk6i/open-oscar-server/blob/main/foodgroup/auth.go"
click node_feedbag "https://github.com/mk6i/open-oscar-server/blob/main/foodgroup/feedbag.go"
click node_icqservices "https://github.com/mk6i/open-oscar-server/blob/main/foodgroup/icq.go"
click node_oservices "https://github.com/mk6i/open-oscar-server/blob/main/foodgroup/oservice.go"
click node_webapi "https://github.com/mk6i/open-oscar-server/blob/main/server/webapi/server.go"
click node_webauth "https://github.com/mk6i/open-oscar-server/blob/main/server/webapi/auth_handler.go"
click node_buddymanager "https://github.com/mk6i/open-oscar-server/blob/main/server/webapi/buddy_list_manager.go"
click node_mgmt "https://github.com/mk6i/open-oscar-server/blob/main/server/http/mgmt_api.go"
click node_session "https://github.com/mk6i/open-oscar-server/blob/main/state/session.go"
click node_sessionmanager "https://github.com/mk6i/open-oscar-server/blob/main/state/session_manager.go"
click node_users "https://github.com/mk6i/open-oscar-server/blob/main/state/user_store.go"
click node_chatstate "https://github.com/mk6i/open-oscar-server/blob/main/state/chat.go"
click node_buddyfeedstate "https://github.com/mk6i/open-oscar-server/blob/main/state/feedbag_list.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_main,node_oscar,node_toc,node_legacy,node_client toneBlue
class node_oscarhandler,node_toccommands,node_legacyservice,node_wire toneAmber
class node_auth,node_feedbag,node_icqservices,node_oservices,node_admin toneMint
class node_session,node_sessionmanager,node_users,node_chatstate,node_buddyfeedstate toneRose
class node_webapi,node_webauth,node_buddymanager,node_mgmt toneIndigo
```

## Components

### Server entry and transports

- [Server process](https://github.com/mk6i/open-oscar-server/blob/main/cmd/server/main.go): `cmd/server/main.go`
- [OSCAR transport](https://github.com/mk6i/open-oscar-server/blob/main/server/oscar/server.go): `server/oscar/server.go`
- [TOC transport](https://github.com/mk6i/open-oscar-server/blob/main/server/toc/server.go): `server/toc/server.go`
- [Legacy ICQ UDP](https://github.com/mk6i/open-oscar-server/blob/main/server/icq_legacy/server.go): `server/icq_legacy/server.go`

### Protocol handling

- [OSCAR handlers](https://github.com/mk6i/open-oscar-server/blob/main/server/oscar/handler.go): `server/oscar/handler.go`
- [TOC commands](https://github.com/mk6i/open-oscar-server/blob/main/server/toc/cmd_client.go): `server/toc/cmd_client.go`
- [Legacy ICQ service](https://github.com/mk6i/open-oscar-server/blob/main/server/icq_legacy/service.go): `server/icq_legacy/service.go`
- [Wire protocol](https://github.com/mk6i/open-oscar-server/blob/main/wire/snacs.go): `wire/snacs.go`

### Messaging services

- [Authentication](https://github.com/mk6i/open-oscar-server/blob/main/foodgroup/auth.go): `foodgroup/auth.go`
- [Buddy lists](https://github.com/mk6i/open-oscar-server/blob/main/foodgroup/feedbag.go): `foodgroup/feedbag.go`
- [ICQ services](https://github.com/mk6i/open-oscar-server/blob/main/foodgroup/icq.go): `foodgroup/icq.go`
- [Session services](https://github.com/mk6i/open-oscar-server/blob/main/foodgroup/oservice.go): `foodgroup/oservice.go`

### Runtime state

- [User sessions](https://github.com/mk6i/open-oscar-server/blob/main/state/session.go): `state/session.go`
- [Session registry](https://github.com/mk6i/open-oscar-server/blob/main/state/session_manager.go): `state/session_manager.go`
- [User accounts](https://github.com/mk6i/open-oscar-server/blob/main/state/user_store.go): `state/user_store.go`
- [Chat state](https://github.com/mk6i/open-oscar-server/blob/main/state/chat.go): `state/chat.go`
- [Buddy-list state](https://github.com/mk6i/open-oscar-server/blob/main/state/feedbag_list.go): `state/feedbag_list.go`

### HTTP APIs

- [AIM Web API](https://github.com/mk6i/open-oscar-server/blob/main/server/webapi/server.go): `server/webapi/server.go`
- [Web authentication](https://github.com/mk6i/open-oscar-server/blob/main/server/webapi/auth_handler.go): `server/webapi/auth_handler.go`
- [Web buddy lists](https://github.com/mk6i/open-oscar-server/blob/main/server/webapi/buddy_list_manager.go): `server/webapi/buddy_list_manager.go`
- [Management API](https://github.com/mk6i/open-oscar-server/blob/main/server/http/mgmt_api.go): `server/http/mgmt_api.go`

### Other components

- **AIM / ICQ clients**
- **Server administrators**

## Connections

- AIM / ICQ clients → OSCAR transport: connects
- AIM / ICQ clients → TOC transport: connects
- AIM / ICQ clients → Legacy ICQ UDP: connects
- Server process → OSCAR transport: starts (evidence: `cmd/server/main.go`)
- Server process → TOC transport: starts (evidence: `cmd/server/main.go`)
- Server process → Management API: starts (evidence: `cmd/server/main.go`)
- Server process → AIM Web API: starts (evidence: `cmd/server/main.go`)
- Server process → Legacy ICQ UDP: starts (evidence: `cmd/server/main.go`)
- OSCAR handlers → Buddy lists: calls (evidence: `server/oscar/handler.go`)
- OSCAR handlers → Authentication: calls
- TOC commands → Session services: calls (evidence: `server/toc/cmd_client.go`)
- TOC commands → Buddy lists: calls (evidence: `server/toc/cmd_client.go`)
- Web buddy lists → Buddy lists: queries (evidence: `server/webapi/buddy_list_manager.go`)
- Session services → User sessions: updates
- Session registry → User sessions: relays (evidence: `state/session_manager.go`)
- Server administrators → Management API: administers
- AIM / ICQ clients → AIM Web API: uses
- AIM Web API → Web authentication: routes
- Legacy ICQ UDP → Legacy ICQ service: dispatches (evidence: `server/icq_legacy/server.go`)
- AIM / ICQ clients → ICQ services: uses
- Wire protocol → OSCAR handlers: encodes frames
- User accounts → User sessions: supports
- Buddy lists → Buddy-list state: updates
- Chat state → Session registry: tracks participants
