# sach-pro/keyflowos architecture

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

- Interactive diagram: https://gitdiagram.com/sach-pro/keyflowos
- Repository: https://github.com/sach-pro/keyflowos

## Overview

KEYFLOW OS is an AI-powered business operating system for small teams. A principal workflow is a user asking KEY to act on business data: the KEY Cortex query pipeline processes the request, applies autonomy and approval oversight, then invokes business capabilities whose results are persisted. The product also includes CRM, finance, bookings, calendar, inbox, integrations, analytics, and public-facing surfaces. Relationships are grounded in the README and SOURCE INDEX references; unsampled capability links are omitted where their runtime wiring is not shown.

Main entry points: [`apps/server/src/modules/key-cortex/key-cortex-query-pipeline.service.ts`](https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/key-cortex/key-cortex-query-pipeline.service.ts) (KEY Cortex), [`apps/server/src/core/prisma/prisma.service.ts`](https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/core/prisma/prisma.service.ts) (Prisma data access), [`apps/server/src/modules/ai/flow-orchestrator.service.ts`](https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/ai/flow-orchestrator.service.ts) (Flow orchestration), [`apps/web`](https://github.com/sach-pro/keyflowos/tree/main/apps/web) (Web workspaces)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["User experience"]
  node_web["Web workspaces"]
  node_crm_ui["CRM pipeline"]
  node_api["NestJS API<br/>[main.ts]"]
end

subgraph group_ai["KEY AI"]
  node_cortex["KEY Cortex"]
  node_model["Model gateway"]
  node_oversight["AI oversight"]
  node_tool_registry["Flow tools"]
  node_flow["Flow orchestration"]
end

subgraph group_operations["Business operations"]
  node_crm["CRM<br/>[crm.service.ts]"]
  node_commerce["Commerce and finance"]
  node_bookings["Bookings"]
  node_calendar["Calendar queries"]
  node_inbox["KEY Inbox"]
  node_analytics["Business analytics"]
  node_public["Public surfaces"]
end

subgraph group_connectors["Ingestion and integrations"]
  node_ingestion["Ingestion review"]
  node_connectors["Connector framework"]
  node_gmail["Gmail ingestion"]
end

subgraph group_platform["Platform services"]
  node_prisma["Prisma data access<br/>[prisma.service.ts]"]
  node_database[("PostgreSQL<br/>[client.ts]")]
  node_redis[("Redis services<br/>[redis.service.ts]")]
end

node_user(("Business user"))
node_external(("External providers"))

node_user -->|"uses"| node_web
node_web -->|"calls API"| node_api
node_user -.->|"asks KEY"| node_cortex
node_api -.->|"routes requests"| node_cortex
node_cortex -->|"queries models"| node_model
node_cortex -.->|"checks autonomy"| node_oversight
node_cortex -.->|"dispatches tools"| node_tool_registry
node_oversight -->|"checks tool risk"| node_tool_registry
node_flow -->|"invokes CRM"| node_crm
node_flow -->|"invokes commerce"| node_commerce
node_flow -->|"invokes bookings"| node_bookings
node_crm_ui -.->|"updates records"| node_api
node_gmail -->|"implements contract"| node_connectors
node_gmail -->|"adds messages"| node_inbox
node_ingestion -->|"upserts threads"| node_inbox
node_ingestion -->|"reads items"| node_prisma
node_calendar -->|"queries data"| node_prisma
node_inbox -->|"stores messages"| node_prisma
node_prisma -->|"uses client"| node_database
node_cortex -->|"uses cache"| node_redis
node_external -.->|"supplies data"| node_connectors
node_web -.->|"presents services"| node_public

click node_web "https://github.com/sach-pro/keyflowos/tree/main/apps/web"
click node_crm_ui "https://github.com/sach-pro/keyflowos/blob/main/apps/web/src/app/app/crm/pipeline/pipeline-toolbar.tsx"
click node_api "https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/main.ts"
click node_cortex "https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/key-cortex/key-cortex-query-pipeline.service.ts"
click node_model "https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/ai/model-gateway.service.ts"
click node_oversight "https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/ai/ai-oversight.service.ts"
click node_tool_registry "https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/ai/flow-tool-registry.ts"
click node_flow "https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/ai/flow-orchestrator.service.ts"
click node_crm "https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/crm/crm.service.ts"
click node_commerce "https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/commerce/commerce.service.ts"
click node_bookings "https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/bookings/bookings.service.ts"
click node_calendar "https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/calendar/calendar-query.service.ts"
click node_inbox "https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/key-inbox/key-inbox.service.ts"
click node_ingestion "https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/ingestion/ingestion-orchestrator.service.ts"
click node_connectors "https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/core/connectors/connector.interface.ts"
click node_gmail "https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/core/connectors/implementations/gmail-ingestion.service.ts"
click node_analytics "https://github.com/sach-pro/keyflowos/tree/main/apps/server/src/modules/analytics"
click node_public "https://github.com/sach-pro/keyflowos/tree/main/apps/server/src/modules/bookings"
click node_prisma "https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/core/prisma/prisma.service.ts"
click node_database "https://github.com/sach-pro/keyflowos/blob/main/packages/db/src/client.ts"
click node_redis "https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/core/redis/redis.service.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_crm_ui,node_api,node_user toneBlue
class node_cortex,node_model,node_oversight,node_tool_registry,node_flow toneAmber
class node_crm,node_commerce,node_bookings,node_calendar,node_inbox,node_analytics,node_public toneMint
class node_ingestion,node_connectors,node_gmail toneRose
class node_prisma,node_database,node_redis,node_external toneIndigo
```

## Components

### User experience

- [Web workspaces](https://github.com/sach-pro/keyflowos/tree/main/apps/web): `apps/web`
- [CRM pipeline](https://github.com/sach-pro/keyflowos/blob/main/apps/web/src/app/app/crm/pipeline/pipeline-toolbar.tsx): `apps/web/src/app/app/crm/pipeline/pipeline-toolbar.tsx`
- [NestJS API](https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/main.ts): `apps/server/src/main.ts`

### KEY AI

- [KEY Cortex](https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/key-cortex/key-cortex-query-pipeline.service.ts): `apps/server/src/modules/key-cortex/key-cortex-query-pipeline.service.ts`
- [Model gateway](https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/ai/model-gateway.service.ts): `apps/server/src/modules/ai/model-gateway.service.ts`
- [AI oversight](https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/ai/ai-oversight.service.ts): `apps/server/src/modules/ai/ai-oversight.service.ts`
- [Flow tools](https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/ai/flow-tool-registry.ts): `apps/server/src/modules/ai/flow-tool-registry.ts`
- [Flow orchestration](https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/ai/flow-orchestrator.service.ts): `apps/server/src/modules/ai/flow-orchestrator.service.ts`

### Business operations

- [CRM](https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/crm/crm.service.ts): `apps/server/src/modules/crm/crm.service.ts`
- [Commerce and finance](https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/commerce/commerce.service.ts): `apps/server/src/modules/commerce/commerce.service.ts`
- [Bookings](https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/bookings/bookings.service.ts): `apps/server/src/modules/bookings/bookings.service.ts`
- [Calendar queries](https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/calendar/calendar-query.service.ts): `apps/server/src/modules/calendar/calendar-query.service.ts`
- [KEY Inbox](https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/key-inbox/key-inbox.service.ts): `apps/server/src/modules/key-inbox/key-inbox.service.ts`
- [Business analytics](https://github.com/sach-pro/keyflowos/tree/main/apps/server/src/modules/analytics): `apps/server/src/modules/analytics`
- [Public surfaces](https://github.com/sach-pro/keyflowos/tree/main/apps/server/src/modules/bookings): `apps/server/src/modules/bookings`

### Ingestion and integrations

- [Ingestion review](https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/modules/ingestion/ingestion-orchestrator.service.ts): `apps/server/src/modules/ingestion/ingestion-orchestrator.service.ts`
- [Connector framework](https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/core/connectors/connector.interface.ts): `apps/server/src/core/connectors/connector.interface.ts`
- [Gmail ingestion](https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/core/connectors/implementations/gmail-ingestion.service.ts): `apps/server/src/core/connectors/implementations/gmail-ingestion.service.ts`

### Platform services

- [Prisma data access](https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/core/prisma/prisma.service.ts): `apps/server/src/core/prisma/prisma.service.ts`
- [PostgreSQL](https://github.com/sach-pro/keyflowos/blob/main/packages/db/src/client.ts): `packages/db/src/client.ts`
- [Redis services](https://github.com/sach-pro/keyflowos/blob/main/apps/server/src/core/redis/redis.service.ts): `apps/server/src/core/redis/redis.service.ts`

### Other components

- **Business user**
- **External providers**

## Connections

- Business user → Web workspaces: uses (evidence: `README.md`)
- Web workspaces → NestJS API: calls API (evidence: `README.md`)
- Business user → KEY Cortex: asks KEY
- NestJS API → KEY Cortex: routes requests
- KEY Cortex → Model gateway: queries models (evidence: `apps/server/src/modules/key-cortex/key-cortex-query-pipeline.service.ts`)
- KEY Cortex → AI oversight: checks autonomy
- KEY Cortex → Flow tools: dispatches tools
- AI oversight → Flow tools: checks tool risk (evidence: `apps/server/src/modules/ai/ai-oversight.service.ts`)
- Flow orchestration → CRM: invokes CRM (evidence: `apps/server/src/modules/ai/flow-orchestrator.service.ts`)
- Flow orchestration → Commerce and finance: invokes commerce (evidence: `apps/server/src/modules/ai/flow-orchestrator.service.ts`)
- Flow orchestration → Bookings: invokes bookings (evidence: `apps/server/src/modules/ai/flow-orchestrator.service.ts`)
- CRM pipeline → NestJS API: updates records
- Gmail ingestion → Connector framework: implements contract (evidence: `apps/server/src/core/connectors/implementations/gmail-ingestion.service.ts`)
- Gmail ingestion → KEY Inbox: adds messages (evidence: `apps/server/src/core/connectors/implementations/gmail-ingestion.service.ts`)
- Ingestion review → KEY Inbox: upserts threads (evidence: `apps/server/src/modules/ingestion/ingestion-orchestrator.service.ts`)
- Ingestion review → Prisma data access: reads items (evidence: `apps/server/src/modules/ingestion/ingestion-orchestrator.service.ts`)
- Calendar queries → Prisma data access: queries data (evidence: `apps/server/src/modules/calendar/calendar-query.service.ts`)
- KEY Inbox → Prisma data access: stores messages (evidence: `apps/server/src/modules/key-inbox/key-inbox.service.ts`)
- Prisma data access → PostgreSQL: uses client (evidence: `apps/server/src/core/prisma/prisma.service.ts`)
- KEY Cortex → Redis services: uses cache (evidence: `apps/server/src/modules/key-cortex/key-cortex-query-pipeline.service.ts`)
- External providers → Connector framework: supplies data
- Web workspaces → Public surfaces: presents services
