# karl-cta/onyka architecture

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

## Overview

Onyka is a self-hosted notes product: users authenticate, capture and organize encrypted notes, then edit and share them, with collaboration and supporting account tools. The graph traces the documented client-to-server boundary and sampled server ownership, while retaining major README capabilities such as Sparks, search, uploads, and administration. Several route, service, and store implementations were not sampled, so links between those layers are shown only where supported by the excerpts or product documentation.

Main entry points: [`apps/web/src/pages/HomePage.tsx`](https://github.com/karl-cta/onyka/blob/main/apps/web/src/pages/HomePage.tsx) (Notes workspace), [`apps/web/src/services/api.ts`](https://github.com/karl-cta/onyka/blob/main/apps/web/src/services/api.ts) (HTTP API client), [`apps/web/src/stores/notes.ts`](https://github.com/karl-cta/onyka/blob/main/apps/web/src/stores/notes.ts) (Client state), [`apps/web/src/App.tsx`](https://github.com/karl-cta/onyka/blob/main/apps/web/src/App.tsx) (App and routes)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Web application"]
  node_webapp["App and routes<br/>[App.tsx]"]
  node_home["Notes workspace<br/>[HomePage.tsx]"]
  node_editor["Rich editor<br/>[NoteEditor.tsx]"]
  node_clientstores["Client state<br/>[notes.ts]"]
  node_api["HTTP API client<br/>[api.ts]"]
end

subgraph group_content["Notes and organization"]
  node_noteroutes["Note routes<br/>[notes.routes.ts]"]
  node_noteservice["Notes service<br/>[notes.service.ts]"]
  node_noterepo["Encrypted note storage<br/>[note.repository.ts]"]
  node_database[("SQLite database<br/>[index.ts]")]
  node_search["Full-text search<br/>[search.service.ts]"]
  node_organization["Folders and tags"]
  node_sparks["Sparks capture<br/>[sparks.service.ts]"]
  node_uploads["Encrypted uploads<br/>[uploads.service.ts]"]
  node_uploadroutes["Upload routes<br/>[uploads.routes.ts]"]
end

subgraph group_identity["Identity and security"]
  node_authroutes["Authentication routes<br/>[auth.routes.ts]"]
  node_authservice["Authentication service<br/>[auth.service.ts]"]
  node_authrepos["Account and token repositories<br/>[user.repository.ts]"]
end

subgraph group_realtime["Collaboration"]
  node_collabhook["Collaboration client"]
  node_collabserver["Collaboration server<br/>[collaboration.ts]"]
end

subgraph group_operations["Product services"]
  node_admin["Admin console API<br/>[admin.routes.ts]"]
  node_adminservice["Administration service<br/>[admin.service.ts]"]
  node_features["Product features"]
  node_sharedtypes["Shared API types"]
end

node_user(("User"))

node_user -->|"uses"| node_webapp
node_webapp -->|"routes to"| node_home
node_home -->|"edits notes"| node_editor
node_home -->|"updates state"| node_clientstores
node_clientstores -->|"requests data"| node_api
node_api -->|"calls API"| node_noteroutes
node_api -->|"calls API"| node_authroutes
node_authroutes -->|"calls"| node_authservice
node_authservice -->|"reads and writes"| node_authrepos
node_noteroutes -->|"calls"| node_noteservice
node_noteservice -->|"reads and writes"| node_noterepo
node_noterepo -->|"stores encrypted notes"| node_database
node_search -->|"queries index"| node_database
node_uploadroutes -->|"validates and processes"| node_uploads
node_api -->|"uploads files"| node_uploadroutes
node_collabhook -->|"syncs edits and presence"| node_collabserver
node_api -->|"calls API"| node_admin
node_admin -->|"calls"| node_adminservice
node_adminservice -->|"rebuilds index"| node_search
node_home -->|"organizes notes"| node_organization
node_home -->|"captures thoughts"| node_sparks
node_home -->|"opens product tools"| node_features
node_clientstores -->|"uses contracts"| node_sharedtypes

click node_webapp "https://github.com/karl-cta/onyka/blob/main/apps/web/src/App.tsx"
click node_home "https://github.com/karl-cta/onyka/blob/main/apps/web/src/pages/HomePage.tsx"
click node_editor "https://github.com/karl-cta/onyka/blob/main/apps/web/src/components/editor/NoteEditor.tsx"
click node_clientstores "https://github.com/karl-cta/onyka/blob/main/apps/web/src/stores/notes.ts"
click node_api "https://github.com/karl-cta/onyka/blob/main/apps/web/src/services/api.ts"
click node_authroutes "https://github.com/karl-cta/onyka/blob/main/apps/server/src/routes/auth.routes.ts"
click node_authservice "https://github.com/karl-cta/onyka/blob/main/apps/server/src/services/auth.service.ts"
click node_authrepos "https://github.com/karl-cta/onyka/blob/main/apps/server/src/repositories/user.repository.ts"
click node_noteroutes "https://github.com/karl-cta/onyka/blob/main/apps/server/src/routes/notes.routes.ts"
click node_noteservice "https://github.com/karl-cta/onyka/blob/main/apps/server/src/services/notes.service.ts"
click node_noterepo "https://github.com/karl-cta/onyka/blob/main/apps/server/src/repositories/note.repository.ts"
click node_database "https://github.com/karl-cta/onyka/blob/main/apps/server/src/db/index.ts"
click node_search "https://github.com/karl-cta/onyka/blob/main/apps/server/src/services/search.service.ts"
click node_organization "https://github.com/karl-cta/onyka/tree/main/apps/server/src/services"
click node_sparks "https://github.com/karl-cta/onyka/blob/main/apps/server/src/services/sparks.service.ts"
click node_uploads "https://github.com/karl-cta/onyka/blob/main/apps/server/src/services/uploads.service.ts"
click node_uploadroutes "https://github.com/karl-cta/onyka/blob/main/apps/server/src/routes/uploads.routes.ts"
click node_collabhook "https://github.com/karl-cta/onyka/blob/main/apps/web/src/hooks/useCollaboration.ts"
click node_collabserver "https://github.com/karl-cta/onyka/blob/main/apps/server/src/websocket/collaboration.ts"
click node_admin "https://github.com/karl-cta/onyka/blob/main/apps/server/src/routes/admin.routes.ts"
click node_adminservice "https://github.com/karl-cta/onyka/blob/main/apps/server/src/services/admin.service.ts"
click node_features "https://github.com/karl-cta/onyka/tree/main/apps/server/src/services"
click node_sharedtypes "https://github.com/karl-cta/onyka/tree/main/packages/shared/src/types"

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_webapp,node_home,node_editor,node_clientstores,node_api,node_user toneBlue
class node_noteroutes,node_noteservice,node_noterepo,node_database,node_search,node_organization,node_sparks,node_uploads,node_uploadroutes toneAmber
class node_authroutes,node_authservice,node_authrepos toneMint
class node_collabhook,node_collabserver toneRose
class node_admin,node_adminservice,node_features,node_sharedtypes toneIndigo
```

## Components

### Web application

- [App and routes](https://github.com/karl-cta/onyka/blob/main/apps/web/src/App.tsx): `apps/web/src/App.tsx`
- [Notes workspace](https://github.com/karl-cta/onyka/blob/main/apps/web/src/pages/HomePage.tsx): `apps/web/src/pages/HomePage.tsx`
- [Rich editor](https://github.com/karl-cta/onyka/blob/main/apps/web/src/components/editor/NoteEditor.tsx): `apps/web/src/components/editor/NoteEditor.tsx`
- [Client state](https://github.com/karl-cta/onyka/blob/main/apps/web/src/stores/notes.ts): `apps/web/src/stores/notes.ts`
- [HTTP API client](https://github.com/karl-cta/onyka/blob/main/apps/web/src/services/api.ts): `apps/web/src/services/api.ts`

### Notes and organization

- [Note routes](https://github.com/karl-cta/onyka/blob/main/apps/server/src/routes/notes.routes.ts): `apps/server/src/routes/notes.routes.ts`
- [Notes service](https://github.com/karl-cta/onyka/blob/main/apps/server/src/services/notes.service.ts): `apps/server/src/services/notes.service.ts`
- [Encrypted note storage](https://github.com/karl-cta/onyka/blob/main/apps/server/src/repositories/note.repository.ts): `apps/server/src/repositories/note.repository.ts`
- [SQLite database](https://github.com/karl-cta/onyka/blob/main/apps/server/src/db/index.ts): `apps/server/src/db/index.ts`
- [Full-text search](https://github.com/karl-cta/onyka/blob/main/apps/server/src/services/search.service.ts): `apps/server/src/services/search.service.ts`
- [Folders and tags](https://github.com/karl-cta/onyka/tree/main/apps/server/src/services): `apps/server/src/services`
- [Sparks capture](https://github.com/karl-cta/onyka/blob/main/apps/server/src/services/sparks.service.ts): `apps/server/src/services/sparks.service.ts`
- [Encrypted uploads](https://github.com/karl-cta/onyka/blob/main/apps/server/src/services/uploads.service.ts): `apps/server/src/services/uploads.service.ts`
- [Upload routes](https://github.com/karl-cta/onyka/blob/main/apps/server/src/routes/uploads.routes.ts): `apps/server/src/routes/uploads.routes.ts`

### Identity and security

- [Authentication routes](https://github.com/karl-cta/onyka/blob/main/apps/server/src/routes/auth.routes.ts): `apps/server/src/routes/auth.routes.ts`
- [Authentication service](https://github.com/karl-cta/onyka/blob/main/apps/server/src/services/auth.service.ts): `apps/server/src/services/auth.service.ts`
- [Account and token repositories](https://github.com/karl-cta/onyka/blob/main/apps/server/src/repositories/user.repository.ts): `apps/server/src/repositories/user.repository.ts`

### Collaboration

- [Collaboration client](https://github.com/karl-cta/onyka/blob/main/apps/web/src/hooks/useCollaboration.ts): `apps/web/src/hooks/useCollaboration.ts`
- [Collaboration server](https://github.com/karl-cta/onyka/blob/main/apps/server/src/websocket/collaboration.ts): `apps/server/src/websocket/collaboration.ts`

### Product services

- [Admin console API](https://github.com/karl-cta/onyka/blob/main/apps/server/src/routes/admin.routes.ts): `apps/server/src/routes/admin.routes.ts`
- [Administration service](https://github.com/karl-cta/onyka/blob/main/apps/server/src/services/admin.service.ts): `apps/server/src/services/admin.service.ts`
- [Product features](https://github.com/karl-cta/onyka/tree/main/apps/server/src/services): `apps/server/src/services`
- [Shared API types](https://github.com/karl-cta/onyka/tree/main/packages/shared/src/types): `packages/shared/src/types`

### Other components

- **User**

## Connections

- User → App and routes: uses
- App and routes → Notes workspace: routes to
- Notes workspace → Rich editor: edits notes
- Notes workspace → Client state: updates state
- Client state → HTTP API client: requests data
- HTTP API client → Note routes: calls API
- HTTP API client → Authentication routes: calls API
- Authentication routes → Authentication service: calls
- Authentication service → Account and token repositories: reads and writes
- Note routes → Notes service: calls
- Notes service → Encrypted note storage: reads and writes
- Encrypted note storage → SQLite database: stores encrypted notes
- Full-text search → SQLite database: queries index
- Upload routes → Encrypted uploads: validates and processes
- HTTP API client → Upload routes: uploads files
- Collaboration client → Collaboration server: syncs edits and presence
- HTTP API client → Admin console API: calls API
- Admin console API → Administration service: calls
- Administration service → Full-text search: rebuilds index
- Notes workspace → Folders and tags: organizes notes
- Notes workspace → Sparks capture: captures thoughts
- Notes workspace → Product features: opens product tools
- Client state → Shared API types: uses contracts