# cyaniagent/asagity architecture

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

## Overview

Asagity is a federated social platform with a React client and two server implementations: the Go Verse Engine and ASP.NET Core Verse API. The main user journey is entering the client, navigating social pages, and using server-backed social or drive features. The README also documents topics, federation, and customizable widget-like UI. The graph reflects wiring visible in sampled entrypoints; endpoint-level calls and several documented capabilities were not sampled, so those connections are intentionally limited.

Main entry points: [`core/src/Verse.Engine/internal/app/app.go`](https://github.com/cyaniagent/asagity/blob/main/core/src/Verse.Engine/internal/app/app.go) (Engine application), [`core/src/Verse.Engine/internal/platform/event/bus.go`](https://github.com/cyaniagent/asagity/blob/main/core/src/Verse.Engine/internal/platform/event/bus.go) (Event bus), [`web/src/components/layout/ClientLayout.tsx`](https://github.com/cyaniagent/asagity/blob/main/web/src/components/layout/ClientLayout.tsx) (Client layout), [`web/src/lib/routes.tsx`](https://github.com/cyaniagent/asagity/blob/main/web/src/lib/routes.tsx) (Page routing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Client experience"]
  node_app["React application<br/>[App.tsx]"]
  node_layout["Client layout<br/>[ClientLayout.tsx]"]
  node_routes["Page routing<br/>[routes.tsx]"]
  node_socialui["Social pages<br/>[TimelineFeed.tsx]"]
  node_driveui["Drive pages<br/>[page.tsx]"]
  node_widgets["Window widgets<br/>[WindowManager.tsx]"]
  node_api_client["API client<br/>[api.ts]"]
end

subgraph group_social["Social platform"]
  node_notes["Notes and topics<br/>[note]"]
  node_follows["Follow graph<br/>[follow]"]
  node_users["Accounts<br/>[user]"]
  node_auth["Authentication<br/>[auth]"]
  node_instances["Instance services<br/>[instance]"]
  node_activitypub["ActivityPub integration<br/>[activitypub]"]
end

subgraph group_services["Server services"]
  node_go_entry["Engine daemon<br/>[main.go]"]
  node_go_app["Engine application<br/>[app.go]"]
  node_drive["Cloud drive<br/>[drive]"]
  node_assets["Asset handling<br/>[asset]"]
  node_api_host["Verse API host<br/>[Program.cs]"]
  node_api_modules["API domain modules<br/>[Verse.Modules]"]
end

subgraph group_infrastructure["Shared runtime"]
  node_events["Event bus<br/>[bus.go]"]
  node_websocket["Live updates<br/>[server.go]"]
  node_database[("Database clients<br/>[database.go]")]
  node_search["Note search<br/>[bleve.go]"]
end

node_visitor(("Visitor"))
node_federated_instances(("Federated servers"))

node_visitor -->|"opens"| node_app
node_app -->|"renders"| node_layout
node_layout -->|"hosts"| node_routes
node_routes -->|"routes to"| node_socialui
node_routes -->|"routes to"| node_driveui
node_layout -->|"mounts"| node_widgets
node_socialui -->|"requests data"| node_api_client
node_driveui -->|"requests data"| node_api_client
node_api_client -->|"HTTP requests"| node_go_entry
node_go_entry -->|"starts"| node_go_app
node_go_app -->|"registers"| node_notes
node_go_app -->|"registers"| node_follows
node_go_app -->|"registers"| node_users
node_go_app -->|"registers"| node_auth
node_go_app -->|"registers"| node_drive
node_go_app -->|"registers"| node_assets
node_go_app -->|"registers"| node_instances
node_go_app -->|"initializes"| node_events
node_go_app -->|"starts"| node_websocket
node_websocket -->|"subscribes"| node_events
node_go_app -->|"uses clients"| node_database
node_go_app -->|"initializes"| node_search
node_notes -->|"uses"| node_search
node_notes -->|"publishes events"| node_events
node_follows -->|"publishes events"| node_events
node_api_host -->|"registers services"| node_api_modules
node_activitypub -.->|"federates with"| node_federated_instances
node_instances -.->|"instance links"| node_federated_instances

click node_app "https://github.com/cyaniagent/asagity/blob/main/web/src/App.tsx"
click node_layout "https://github.com/cyaniagent/asagity/blob/main/web/src/components/layout/ClientLayout.tsx"
click node_routes "https://github.com/cyaniagent/asagity/blob/main/web/src/lib/routes.tsx"
click node_socialui "https://github.com/cyaniagent/asagity/blob/main/web/src/components/post/TimelineFeed.tsx"
click node_driveui "https://github.com/cyaniagent/asagity/blob/main/web/src/pages/drive/page.tsx"
click node_widgets "https://github.com/cyaniagent/asagity/blob/main/web/src/components/windows/WindowManager.tsx"
click node_api_client "https://github.com/cyaniagent/asagity/blob/main/web/src/lib/api.ts"
click node_go_entry "https://github.com/cyaniagent/asagity/blob/main/core/src/Verse.Engine/cmd/verse-engine/main.go"
click node_go_app "https://github.com/cyaniagent/asagity/blob/main/core/src/Verse.Engine/internal/app/app.go"
click node_notes "https://github.com/cyaniagent/asagity/tree/main/core/src/Verse.Engine/internal/module/note"
click node_follows "https://github.com/cyaniagent/asagity/tree/main/core/src/Verse.Engine/internal/module/follow"
click node_users "https://github.com/cyaniagent/asagity/tree/main/core/src/Verse.Engine/internal/module/user"
click node_auth "https://github.com/cyaniagent/asagity/tree/main/core/src/Verse.Engine/internal/module/auth"
click node_drive "https://github.com/cyaniagent/asagity/tree/main/core/src/Verse.Engine/internal/module/drive"
click node_assets "https://github.com/cyaniagent/asagity/tree/main/core/src/Verse.Engine/internal/module/asset"
click node_instances "https://github.com/cyaniagent/asagity/tree/main/core/src/Verse.Engine/internal/module/instance"
click node_activitypub "https://github.com/cyaniagent/asagity/tree/main/core/src/Verse.Engine/internal/app/connections/activitypub"
click node_events "https://github.com/cyaniagent/asagity/blob/main/core/src/Verse.Engine/internal/platform/event/bus.go"
click node_websocket "https://github.com/cyaniagent/asagity/blob/main/core/src/Verse.Engine/internal/platform/ws/server.go"
click node_database "https://github.com/cyaniagent/asagity/blob/main/core/src/Verse.Engine/internal/platform/database/database.go"
click node_search "https://github.com/cyaniagent/asagity/blob/main/core/src/Verse.Engine/internal/platform/search/bleve.go"
click node_api_host "https://github.com/cyaniagent/asagity/blob/main/core/src/Verse.Api/Program.cs"
click node_api_modules "https://github.com/cyaniagent/asagity/tree/main/core/src/Verse.Modules"

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_app,node_layout,node_routes,node_socialui,node_driveui,node_widgets,node_api_client toneBlue
class node_notes,node_follows,node_users,node_auth,node_instances,node_activitypub toneAmber
class node_go_entry,node_go_app,node_drive,node_assets,node_api_host,node_api_modules,node_federated_instances toneMint
class node_events,node_websocket,node_database,node_search toneRose
class node_visitor toneIndigo
```

## Components

### Client experience

- [React application](https://github.com/cyaniagent/asagity/blob/main/web/src/App.tsx): `web/src/App.tsx`
- [Client layout](https://github.com/cyaniagent/asagity/blob/main/web/src/components/layout/ClientLayout.tsx): `web/src/components/layout/ClientLayout.tsx`
- [Page routing](https://github.com/cyaniagent/asagity/blob/main/web/src/lib/routes.tsx): `web/src/lib/routes.tsx`
- [Social pages](https://github.com/cyaniagent/asagity/blob/main/web/src/components/post/TimelineFeed.tsx): `web/src/components/post/TimelineFeed.tsx`
- [Drive pages](https://github.com/cyaniagent/asagity/blob/main/web/src/pages/drive/page.tsx): `web/src/pages/drive/page.tsx`
- [Window widgets](https://github.com/cyaniagent/asagity/blob/main/web/src/components/windows/WindowManager.tsx): `web/src/components/windows/WindowManager.tsx`
- [API client](https://github.com/cyaniagent/asagity/blob/main/web/src/lib/api.ts): `web/src/lib/api.ts`

### Social platform

- [Notes and topics](https://github.com/cyaniagent/asagity/tree/main/core/src/Verse.Engine/internal/module/note): `core/src/Verse.Engine/internal/module/note`
- [Follow graph](https://github.com/cyaniagent/asagity/tree/main/core/src/Verse.Engine/internal/module/follow): `core/src/Verse.Engine/internal/module/follow`
- [Accounts](https://github.com/cyaniagent/asagity/tree/main/core/src/Verse.Engine/internal/module/user): `core/src/Verse.Engine/internal/module/user`
- [Authentication](https://github.com/cyaniagent/asagity/tree/main/core/src/Verse.Engine/internal/module/auth): `core/src/Verse.Engine/internal/module/auth`
- [Instance services](https://github.com/cyaniagent/asagity/tree/main/core/src/Verse.Engine/internal/module/instance): `core/src/Verse.Engine/internal/module/instance`
- [ActivityPub integration](https://github.com/cyaniagent/asagity/tree/main/core/src/Verse.Engine/internal/app/connections/activitypub): `core/src/Verse.Engine/internal/app/connections/activitypub`

### Server services

- [Engine daemon](https://github.com/cyaniagent/asagity/blob/main/core/src/Verse.Engine/cmd/verse-engine/main.go): `core/src/Verse.Engine/cmd/verse-engine/main.go`
- [Engine application](https://github.com/cyaniagent/asagity/blob/main/core/src/Verse.Engine/internal/app/app.go): `core/src/Verse.Engine/internal/app/app.go`
- [Cloud drive](https://github.com/cyaniagent/asagity/tree/main/core/src/Verse.Engine/internal/module/drive): `core/src/Verse.Engine/internal/module/drive`
- [Asset handling](https://github.com/cyaniagent/asagity/tree/main/core/src/Verse.Engine/internal/module/asset): `core/src/Verse.Engine/internal/module/asset`
- [Verse API host](https://github.com/cyaniagent/asagity/blob/main/core/src/Verse.Api/Program.cs): `core/src/Verse.Api/Program.cs`
- [API domain modules](https://github.com/cyaniagent/asagity/tree/main/core/src/Verse.Modules): `core/src/Verse.Modules`

### Shared runtime

- [Event bus](https://github.com/cyaniagent/asagity/blob/main/core/src/Verse.Engine/internal/platform/event/bus.go): `core/src/Verse.Engine/internal/platform/event/bus.go`
- [Live updates](https://github.com/cyaniagent/asagity/blob/main/core/src/Verse.Engine/internal/platform/ws/server.go): `core/src/Verse.Engine/internal/platform/ws/server.go`
- [Database clients](https://github.com/cyaniagent/asagity/blob/main/core/src/Verse.Engine/internal/platform/database/database.go): `core/src/Verse.Engine/internal/platform/database/database.go`
- [Note search](https://github.com/cyaniagent/asagity/blob/main/core/src/Verse.Engine/internal/platform/search/bleve.go): `core/src/Verse.Engine/internal/platform/search/bleve.go`

### Other components

- **Visitor**
- **Federated servers**

## Connections

- Visitor → React application: opens
- React application → Client layout: renders
- Client layout → Page routing: hosts
- Page routing → Social pages: routes to
- Page routing → Drive pages: routes to
- Client layout → Window widgets: mounts
- Social pages → API client: requests data
- Drive pages → API client: requests data
- API client → Engine daemon: HTTP requests
- Engine daemon → Engine application: starts
- Engine application → Notes and topics: registers
- Engine application → Follow graph: registers
- Engine application → Accounts: registers
- Engine application → Authentication: registers
- Engine application → Cloud drive: registers
- Engine application → Asset handling: registers
- Engine application → Instance services: registers
- Engine application → Event bus: initializes
- Engine application → Live updates: starts
- Live updates → Event bus: subscribes
- Engine application → Database clients: uses clients
- Engine application → Note search: initializes
- Notes and topics → Note search: uses
- Notes and topics → Event bus: publishes events
- Follow graph → Event bus: publishes events
- Verse API host → API domain modules: registers services
- ActivityPub integration → Federated servers: federates with
- Instance services → Federated servers: instance links