# crydensync/api architecture

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

- Interactive diagram: https://gitdiagram.com/crydensync/api
- Repository: https://github.com/crydensync/api

## Overview

Cryden API is a self-hosted HTTP wrapper for CrydenSync, backed by Postgres or (for core authentication only) SQLite. Its main user workflow is an HTTP client reaching routed authentication or account endpoints, which invoke Cryden’s auth engine and return tokens or account results. The Postgres-only admin console adds user metadata, anomaly review, logs, webhooks, digests, and AI configuration; signed-in users can also ask the AI widget questions. Unsampled handler and wiring details are represented only where the README or SOURCE INDEX documents them.

Main entry points: [`httpapi/router.go`](https://github.com/crydensync/api/blob/main/httpapi/router.go) (HTTP router), [`main.go`](https://github.com/crydensync/api/blob/main/main.go) (API server), [`askai/askai.go`](https://github.com/crydensync/api/blob/main/askai/askai.go) (AI query service), [`httpapi/oauth_handlers.go`](https://github.com/crydensync/api/blob/main/httpapi/oauth_handlers.go) (OAuth flows)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Server runtime"]
  node_server["API server<br/>[main.go]"]
  node_router["HTTP router<br/>[router.go]"]
  node_database[("Deployment database")]
end

subgraph group_identity["Identity API"]
  node_auth["Authentication<br/>[auth_handlers.go]"]
  node_sessions["Sessions"]
  node_oauth["OAuth flows<br/>[oauth_handlers.go]"]
end

subgraph group_console["Admin console"]
  node_useradmin["User administration<br/>[user_handlers.go]"]
  node_metadata["User metadata"]
  node_anomalies["Anomaly review"]
  node_settingsapi["Settings API"]
  node_settingsstore[("Settings storage<br/>[store.go]")]
  node_shiplog[("Shipped logs<br/>[store.go]")]
  node_digest["Digest scheduling<br/>[schedule.go]"]
  node_webhook["Webhook delivery<br/>[worker.go]"]
end

subgraph group_ai["AI query"]
  node_askroute["Ask AI endpoint<br/>[widget_handlers.go]"]
  node_askservice["AI query service<br/>[askai.go]"]
  node_providers["AI providers<br/>[anthropic.go]"]
  node_snapshot["Read-only SQL query<br/>[query.go]"]
end

node_client(("HTTP client"))
node_oauthproviders["OAuth providers"]
node_llm["LLM service"]

node_client -->|"sends HTTP"| node_router
node_server -->|"configures"| node_router
node_server -->|"opens and migrates"| node_database
node_router -->|"routes auth"| node_auth
node_router -->|"routes sessions"| node_sessions
node_router -->|"routes OAuth"| node_oauth
node_oauth -->|"exchanges identity"| node_oauthproviders
node_router -->|"routes admin"| node_useradmin
node_router -->|"routes admin"| node_metadata
node_router -->|"routes review"| node_anomalies
node_router -->|"routes settings"| node_settingsapi
node_settingsapi -->|"reads and writes"| node_settingsstore
node_router -->|"routes log history"| node_shiplog
node_server -->|"starts scheduler"| node_digest
node_server -->|"starts worker"| node_webhook
node_router -->|"routes widget"| node_askroute
node_askroute -.->|"serves questions"| node_askservice
node_askservice -->|"loads configuration"| node_settingsstore
node_askservice -->|"builds provider"| node_providers
node_providers -.->|"requests completion"| node_llm
node_askservice -.->|"queries data"| node_snapshot
node_snapshot -->|"reads scoped data"| node_database

click node_server "https://github.com/crydensync/api/blob/main/main.go"
click node_router "https://github.com/crydensync/api/blob/main/httpapi/router.go"
click node_auth "https://github.com/crydensync/api/blob/main/httpapi/auth_handlers.go"
click node_sessions "https://github.com/crydensync/api/blob/main/httpapi/session_handlers.go"
click node_oauth "https://github.com/crydensync/api/blob/main/httpapi/oauth_handlers.go"
click node_useradmin "https://github.com/crydensync/api/blob/main/httpapi/user_handlers.go"
click node_metadata "https://github.com/crydensync/api/blob/main/httpapi/metadata_handlers.go"
click node_anomalies "https://github.com/crydensync/api/blob/main/httpapi/anomaly_handlers.go"
click node_settingsapi "https://github.com/crydensync/api/blob/main/httpapi/settings_handlers.go"
click node_settingsstore "https://github.com/crydensync/api/blob/main/settings/store.go"
click node_shiplog "https://github.com/crydensync/api/blob/main/shiplog/store.go"
click node_digest "https://github.com/crydensync/api/blob/main/digest/schedule.go"
click node_webhook "https://github.com/crydensync/api/blob/main/webhook/worker.go"
click node_askroute "https://github.com/crydensync/api/blob/main/httpapi/widget_handlers.go"
click node_askservice "https://github.com/crydensync/api/blob/main/askai/askai.go"
click node_providers "https://github.com/crydensync/api/blob/main/aiprovider/anthropic.go"
click node_snapshot "https://github.com/crydensync/api/blob/main/aiprovider/query.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_router,node_database,node_client toneBlue
class node_auth,node_sessions,node_oauth toneAmber
class node_useradmin,node_metadata,node_anomalies,node_settingsapi,node_settingsstore,node_shiplog,node_digest,node_webhook toneMint
class node_askroute,node_askservice,node_providers,node_snapshot toneRose
class node_oauthproviders,node_llm toneIndigo
```

## Components

### Server runtime

- [API server](https://github.com/crydensync/api/blob/main/main.go): `main.go`
- [HTTP router](https://github.com/crydensync/api/blob/main/httpapi/router.go): `httpapi/router.go`
- **Deployment database**

### Identity API

- [Authentication](https://github.com/crydensync/api/blob/main/httpapi/auth_handlers.go): `httpapi/auth_handlers.go`
- [Sessions](https://github.com/crydensync/api/blob/main/httpapi/session_handlers.go): `httpapi/session_handlers.go`
- [OAuth flows](https://github.com/crydensync/api/blob/main/httpapi/oauth_handlers.go): `httpapi/oauth_handlers.go`

### Admin console

- [User administration](https://github.com/crydensync/api/blob/main/httpapi/user_handlers.go): `httpapi/user_handlers.go`
- [User metadata](https://github.com/crydensync/api/blob/main/httpapi/metadata_handlers.go): `httpapi/metadata_handlers.go`
- [Anomaly review](https://github.com/crydensync/api/blob/main/httpapi/anomaly_handlers.go): `httpapi/anomaly_handlers.go`
- [Settings API](https://github.com/crydensync/api/blob/main/httpapi/settings_handlers.go): `httpapi/settings_handlers.go`
- [Settings storage](https://github.com/crydensync/api/blob/main/settings/store.go): `settings/store.go`
- [Shipped logs](https://github.com/crydensync/api/blob/main/shiplog/store.go): `shiplog/store.go`
- [Digest scheduling](https://github.com/crydensync/api/blob/main/digest/schedule.go): `digest/schedule.go`
- [Webhook delivery](https://github.com/crydensync/api/blob/main/webhook/worker.go): `webhook/worker.go`

### AI query

- [Ask AI endpoint](https://github.com/crydensync/api/blob/main/httpapi/widget_handlers.go): `httpapi/widget_handlers.go`
- [AI query service](https://github.com/crydensync/api/blob/main/askai/askai.go): `askai/askai.go`
- [AI providers](https://github.com/crydensync/api/blob/main/aiprovider/anthropic.go): `aiprovider/anthropic.go`
- [Read-only SQL query](https://github.com/crydensync/api/blob/main/aiprovider/query.go): `aiprovider/query.go`

### Other components

- **HTTP client**
- **OAuth providers**
- **LLM service**

## Connections

- HTTP client → HTTP router: sends HTTP (evidence: `README.md`)
- API server → HTTP router: configures (evidence: `main.go`)
- API server → Deployment database: opens and migrates (evidence: `README.md`)
- HTTP router → Authentication: routes auth (evidence: `httpapi/router.go`)
- HTTP router → Sessions: routes sessions (evidence: `httpapi/router.go`)
- HTTP router → OAuth flows: routes OAuth (evidence: `httpapi/router.go`)
- OAuth flows → OAuth providers: exchanges identity (evidence: `httpapi/oauth_handlers.go`)
- HTTP router → User administration: routes admin (evidence: `httpapi/router.go`)
- HTTP router → User metadata: routes admin (evidence: `httpapi/router.go`)
- HTTP router → Anomaly review: routes review (evidence: `httpapi/router.go`)
- HTTP router → Settings API: routes settings (evidence: `httpapi/router.go`)
- Settings API → Settings storage: reads and writes (evidence: `httpapi/settings_handlers.go`)
- HTTP router → Shipped logs: routes log history (evidence: `httpapi/router.go`)
- API server → Digest scheduling: starts scheduler (evidence: `main.go`)
- API server → Webhook delivery: starts worker (evidence: `main.go`)
- HTTP router → Ask AI endpoint: routes widget (evidence: `httpapi/router.go`)
- Ask AI endpoint → AI query service: serves questions
- AI query service → Settings storage: loads configuration (evidence: `askai/askai.go`)
- AI query service → AI providers: builds provider (evidence: `askai/askai.go`)
- AI providers → LLM service: requests completion
- AI query service → Read-only SQL query: queries data
- Read-only SQL query → Deployment database: reads scoped data (evidence: `aiprovider/query.go`)
