# usekaneo/kaneo architecture

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

- Interactive diagram: https://gitdiagram.com/usekaneo/kaneo
- Repository: https://github.com/usekaneo/kaneo

## Overview

Kaneo is a project-management product: people organize team workspaces and projects, manage tasks and their context, and collaborate through views, notifications, and integrations. The graph centers on the documented user-to-result workflow and the API’s persistence layer, while retaining major documented capabilities whose implementation was not sampled. Edges reflect README statements or visible imports/calls; unsampled feature links are omitted rather than inferred.

Main entry points: [`apps/api/src/index.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts) (HTTP API), [`apps/api/src/plugins/github/services/link-manager.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/github/services/link-manager.ts) (GitHub sync), [`apps/web/src/main.tsx`](https://github.com/usekaneo/kaneo/blob/main/apps/web/src/main.tsx) (Web workspace), [`apps/mobile/src/lib/api/client.ts`](https://github.com/usekaneo/kaneo/blob/main/apps/mobile/src/lib/api/client.ts) (Mobile client)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_work["Work management"]
  node_web["Web workspace<br/>[main.tsx]"]
  node_mobile["Mobile client<br/>[client.ts]"]
  node_projects["Projects and views<br/>[index.ts]"]
  node_tasks["Tasks and subtasks"]
  node_columns["Workflow columns<br/>[create-column.ts]"]
  node_fields["Custom fields"]
  node_labels["Labels"]
end

subgraph group_collab["Team collaboration"]
  node_comments["Comments and activity<br/>[create-comment.ts]"]
  node_workspace["Workspace and roles"]
  node_invitations["Invitations<br/>[index.ts]"]
  node_notifications["Notifications"]
  node_preferences["Notification delivery<br/>[delivery.ts]"]
end

subgraph group_integrations["Integrations and access"]
  node_github["GitHub sync<br/>[link-manager.ts]"]
  node_gitea["Gitea integration<br/>[webhook-handler.ts]"]
  node_chat["Chat integrations<br/>[events.ts]"]
  node_webhooks["Project webhooks<br/>[events.ts]"]
  node_import["Project import<br/>[run-import-job.ts]"]
  node_cli["CLI<br/>[main.ts]"]
  node_mcp["MCP server<br/>[server.ts]"]
end

subgraph group_platform["API and persistence"]
  node_api["HTTP API<br/>[index.ts]"]
  node_database[("Relational data<br/>[schema.ts]")]
end

node_person(("Team member"))
node_external["Connected services"]

node_person -->|"uses"| node_web
node_person -->|"uses"| node_mobile
node_web -.->|"requests"| node_api
node_mobile -.->|"requests"| node_api
node_api -.->|"routes project work"| node_projects
node_api -.->|"routes task work"| node_tasks
node_api -.->|"routes column work"| node_columns
node_api -.->|"routes field work"| node_fields
node_api -.->|"routes label work"| node_labels
node_api -.->|"routes collaboration"| node_comments
node_api -.->|"manages membership"| node_workspace
node_api -.->|"handles invitations"| node_invitations
node_api -.->|"serves notifications"| node_notifications
node_api -.->|"persists data"| node_database
node_github -->|"stores link state"| node_database
node_github -.->|"syncs repository activity"| node_external
node_gitea -.->|"connects repositories"| node_external
node_chat -.->|"sends updates"| node_external
node_webhooks -.->|"sends events"| node_external
node_import -.->|"imports project data"| node_projects
node_person -->|"uses"| node_cli
node_cli -.->|"requests"| node_api
node_person -->|"connects assistant"| node_mcp
node_mcp -.->|"calls Kaneo API"| node_api
node_notifications -.->|"honors delivery settings"| node_preferences

click node_web "https://github.com/usekaneo/kaneo/blob/main/apps/web/src/main.tsx"
click node_mobile "https://github.com/usekaneo/kaneo/blob/main/apps/mobile/src/lib/api/client.ts"
click node_projects "https://github.com/usekaneo/kaneo/blob/main/apps/api/src/project/index.ts"
click node_tasks "https://github.com/usekaneo/kaneo/blob/main/apps/api/src/task/controllers/bulk-update-tasks.ts"
click node_columns "https://github.com/usekaneo/kaneo/blob/main/apps/api/src/column/controllers/create-column.ts"
click node_fields "https://github.com/usekaneo/kaneo/blob/main/apps/api/src/custom-field/controllers/set-custom-field-value.ts"
click node_labels "https://github.com/usekaneo/kaneo/blob/main/apps/api/src/label/controllers/assign-label-to-task.ts"
click node_comments "https://github.com/usekaneo/kaneo/blob/main/apps/api/src/comment/controllers/create-comment.ts"
click node_workspace "https://github.com/usekaneo/kaneo/blob/main/apps/api/src/admin/controllers/add-workspace-member.ts"
click node_invitations "https://github.com/usekaneo/kaneo/blob/main/apps/api/src/invitation/index.ts"
click node_notifications "https://github.com/usekaneo/kaneo/blob/main/apps/api/src/notification/controllers/get-notifications.ts"
click node_preferences "https://github.com/usekaneo/kaneo/blob/main/apps/api/src/notification-preferences/delivery.ts"
click node_api "https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts"
click node_database "https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts"
click node_github "https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/github/services/link-manager.ts"
click node_gitea "https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/gitea/webhook-handler.ts"
click node_chat "https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/slack/events.ts"
click node_webhooks "https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/generic-webhook/events.ts"
click node_import "https://github.com/usekaneo/kaneo/blob/main/apps/api/src/import/run-import-job.ts"
click node_cli "https://github.com/usekaneo/kaneo/blob/main/packages/cli/src/main.ts"
click node_mcp "https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/server.ts"

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_web,node_mobile,node_projects,node_tasks,node_columns,node_fields,node_labels toneBlue
class node_comments,node_workspace,node_invitations,node_notifications,node_preferences toneAmber
class node_github,node_gitea,node_chat,node_webhooks,node_import,node_cli,node_mcp toneMint
class node_api,node_database toneRose
class node_person,node_external toneIndigo
```

## Components

### Work management

- [Web workspace](https://github.com/usekaneo/kaneo/blob/main/apps/web/src/main.tsx): `apps/web/src/main.tsx`
- [Mobile client](https://github.com/usekaneo/kaneo/blob/main/apps/mobile/src/lib/api/client.ts): `apps/mobile/src/lib/api/client.ts`
- [Projects and views](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/project/index.ts): `apps/api/src/project/index.ts`
- [Tasks and subtasks](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/task/controllers/bulk-update-tasks.ts): `apps/api/src/task/controllers/bulk-update-tasks.ts`
- [Workflow columns](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/column/controllers/create-column.ts): `apps/api/src/column/controllers/create-column.ts`
- [Custom fields](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/custom-field/controllers/set-custom-field-value.ts): `apps/api/src/custom-field/controllers/set-custom-field-value.ts`
- [Labels](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/label/controllers/assign-label-to-task.ts): `apps/api/src/label/controllers/assign-label-to-task.ts`

### Team collaboration

- [Comments and activity](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/comment/controllers/create-comment.ts): `apps/api/src/comment/controllers/create-comment.ts`
- [Workspace and roles](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/admin/controllers/add-workspace-member.ts): `apps/api/src/admin/controllers/add-workspace-member.ts`
- [Invitations](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/invitation/index.ts): `apps/api/src/invitation/index.ts`
- [Notifications](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/notification/controllers/get-notifications.ts): `apps/api/src/notification/controllers/get-notifications.ts`
- [Notification delivery](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/notification-preferences/delivery.ts): `apps/api/src/notification-preferences/delivery.ts`

### Integrations and access

- [GitHub sync](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/github/services/link-manager.ts): `apps/api/src/plugins/github/services/link-manager.ts`
- [Gitea integration](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/gitea/webhook-handler.ts): `apps/api/src/plugins/gitea/webhook-handler.ts`
- [Chat integrations](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/slack/events.ts): `apps/api/src/plugins/slack/events.ts`
- [Project webhooks](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/plugins/generic-webhook/events.ts): `apps/api/src/plugins/generic-webhook/events.ts`
- [Project import](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/import/run-import-job.ts): `apps/api/src/import/run-import-job.ts`
- [CLI](https://github.com/usekaneo/kaneo/blob/main/packages/cli/src/main.ts): `packages/cli/src/main.ts`
- [MCP server](https://github.com/usekaneo/kaneo/blob/main/packages/mcp/src/server.ts): `packages/mcp/src/server.ts`

### API and persistence

- [HTTP API](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/index.ts): `apps/api/src/index.ts`
- [Relational data](https://github.com/usekaneo/kaneo/blob/main/apps/api/src/database/schema.ts): `apps/api/src/database/schema.ts`

### Other components

- **Team member**
- **Connected services**

## Connections

- Team member → Web workspace: uses (evidence: `README.md`)
- Team member → Mobile client: uses (evidence: `README.md`)
- Web workspace → HTTP API: requests
- Mobile client → HTTP API: requests
- HTTP API → Projects and views: routes project work
- HTTP API → Tasks and subtasks: routes task work
- HTTP API → Workflow columns: routes column work
- HTTP API → Custom fields: routes field work
- HTTP API → Labels: routes label work
- HTTP API → Comments and activity: routes collaboration
- HTTP API → Workspace and roles: manages membership
- HTTP API → Invitations: handles invitations
- HTTP API → Notifications: serves notifications
- HTTP API → Relational data: persists data
- GitHub sync → Relational data: stores link state (evidence: `apps/api/src/plugins/github/services/link-manager.ts`)
- GitHub sync → Connected services: syncs repository activity (evidence: `README.md`)
- Gitea integration → Connected services: connects repositories (evidence: `README.md`)
- Chat integrations → Connected services: sends updates (evidence: `README.md`)
- Project webhooks → Connected services: sends events (evidence: `README.md`)
- Project import → Projects and views: imports project data
- Team member → CLI: uses (evidence: `README.md`)
- CLI → HTTP API: requests
- Team member → MCP server: connects assistant (evidence: `README.md`)
- MCP server → HTTP API: calls Kaneo API
- Notifications → Notification delivery: honors delivery settings