# clarke-ro/chief architecture

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

- Interactive diagram: https://gitdiagram.com/clarke-ro/chief
- Repository: https://github.com/clarke-ro/chief

## Overview

Chief is a mobile-first AI chief-of-staff product: users connect work accounts, synchronize provider data, and receive ranked priorities, a synthesized daily brief, schedule, and context-grounded chat. The Expo client uses authenticated API services; the Nest backend handles integrations, sync, workspace understanding, and AI reasoning, with PostgreSQL and Redis-backed jobs. The graph preserves documented app surfaces and backend stages. Some subsystem links rely on README-level architecture because their implementations were not sampled; those links are cited to the README.

Main entry points: [`backend/src/sync/pipeline/sync-pipeline.service.ts`](https://github.com/clarke-ro/chief/blob/main/backend/src/sync/pipeline/sync-pipeline.service.ts) (Sync pipeline), [`src/services/api/client.ts`](https://github.com/clarke-ro/chief/blob/main/src/services/api/client.ts) (API client), [`src/features/chief/ChiefScreen.tsx`](https://github.com/clarke-ro/chief/blob/main/src/features/chief/ChiefScreen.tsx) (Ask Chief), [`backend/src/briefing/briefing.service.ts`](https://github.com/clarke-ro/chief/blob/main/backend/src/briefing/briefing.service.ts) (Briefing and ranking)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["Expo client"]
  node_client_auth["Client auth<br/>[authService.ts]"]
  node_api_client["API client<br/>[client.ts]"]
end

subgraph group_user_workflows["User workflows"]
  node_onboarding["Onboarding"]
  node_home_brief["Home brief<br/>[HomeScreen.tsx]"]
  node_today_plan["Today schedule<br/>[TasksScreen.tsx]"]
  node_chief_chat["Ask Chief<br/>[ChiefScreen.tsx]"]
  node_actions["Contextual actions<br/>[actionRouter.ts]"]
  node_analytics["Analytics"]
  node_profile["Profile and settings<br/>[ProfileScreen.tsx]"]
end

subgraph group_integration_sync["Integrations and sync"]
  node_integrations_api["Integration management"]
  node_oauth["OAuth flow<br/>[oauth.service.ts]"]
  node_provider_registry["Provider adapters"]
  node_sync_orchestrator["Sync orchestration"]
  node_sync_pipeline["Sync pipeline"]
  node_sync_fetch["Provider fetchers"]
  node_sync_normalize_persist["Normalize and persist"]
end

subgraph group_workspace_intelligence["Workspace intelligence"]
  node_briefing["Briefing and ranking"]
  node_relevance["Relevance scoring"]
  node_knowledge["Knowledge snapshot"]
  node_workspace_engine["Workspace understanding"]
  node_context_engine["Chat context"]
  node_reasoning["AI reasoning"]
end

subgraph group_backend_platform["Backend platform"]
  node_database[("PostgreSQL<br/>[prisma.service.ts]")]
  node_queue["Redis and BullMQ<br/>[queue.service.ts]"]
  node_worker["Background worker"]
end

node_user(("Chief user"))
node_providers["Connected work apps"]

node_user -->|"connects accounts"| node_onboarding
node_onboarding -->|"authenticates with"| node_client_auth
node_client_auth -->|"bootstraps session"| node_api_client
node_user -->|"views priorities"| node_home_brief
node_home_brief -->|"loads brief"| node_api_client
node_user -->|"plans day"| node_today_plan
node_today_plan -->|"refreshes schedule"| node_api_client
node_user -->|"asks question"| node_chief_chat
node_chief_chat -->|"posts chat"| node_api_client
node_user -->|"chooses action"| node_actions
node_user -->|"reviews impact"| node_analytics
node_user -->|"manages account"| node_profile
node_api_client -->|"calls API"| node_integrations_api
node_integrations_api -->|"starts OAuth"| node_oauth
node_oauth -->|"selects provider"| node_provider_registry
node_providers -->|"authorizes access"| node_oauth
node_provider_registry -->|"provides adapters"| node_sync_orchestrator
node_sync_orchestrator -->|"dispatches resource jobs"| node_sync_pipeline
node_sync_pipeline -->|"fetches provider data"| node_sync_fetch
node_sync_pipeline -->|"persists fetched batch"| node_sync_normalize_persist
node_sync_normalize_persist -.->|"writes records"| node_database
node_sync_pipeline -->|"queues fresh brief"| node_briefing
node_sync_orchestrator -->|"enqueues sync jobs"| node_queue
node_queue -->|"delivers jobs"| node_worker
node_worker -->|"runs sync"| node_sync_pipeline
node_briefing -->|"ranks candidates"| node_relevance
node_briefing -->|"reads workspace data"| node_database
node_knowledge -->|"loads snapshot"| node_database
node_workspace_engine -->|"builds on brief"| node_briefing
node_workspace_engine -->|"loads knowledge"| node_knowledge
node_chief_chat -->|"requests context"| node_context_engine
node_context_engine -->|"builds workspace snapshot"| node_workspace_engine
node_context_engine -->|"supplies structured context"| node_reasoning
node_reasoning -->|"returns reply"| node_chief_chat

click node_onboarding "https://github.com/clarke-ro/chief/blob/main/src/features/onboarding/screens/ConnectAppsScreen.tsx"
click node_client_auth "https://github.com/clarke-ro/chief/blob/main/src/services/auth/authService.ts"
click node_api_client "https://github.com/clarke-ro/chief/blob/main/src/services/api/client.ts"
click node_home_brief "https://github.com/clarke-ro/chief/blob/main/src/features/brief/HomeScreen.tsx"
click node_today_plan "https://github.com/clarke-ro/chief/blob/main/src/features/tasks/TasksScreen.tsx"
click node_chief_chat "https://github.com/clarke-ro/chief/blob/main/src/features/chief/ChiefScreen.tsx"
click node_actions "https://github.com/clarke-ro/chief/blob/main/src/features/actions/actionRouter.ts"
click node_analytics "https://github.com/clarke-ro/chief/blob/main/src/features/analytics/AnalyticsScreen.tsx"
click node_profile "https://github.com/clarke-ro/chief/blob/main/src/features/profile/ProfileScreen.tsx"
click node_integrations_api "https://github.com/clarke-ro/chief/blob/main/backend/src/integrations/integrations.service.ts"
click node_oauth "https://github.com/clarke-ro/chief/blob/main/backend/src/integrations/oauth/oauth.service.ts"
click node_provider_registry "https://github.com/clarke-ro/chief/blob/main/backend/src/integrations/providers/provider.registry.ts"
click node_sync_orchestrator "https://github.com/clarke-ro/chief/blob/main/backend/src/sync/orchestrator/sync-orchestrator.service.ts"
click node_sync_pipeline "https://github.com/clarke-ro/chief/blob/main/backend/src/sync/pipeline/sync-pipeline.service.ts"
click node_sync_fetch "https://github.com/clarke-ro/chief/tree/main/backend/src/sync/fetch"
click node_sync_normalize_persist "https://github.com/clarke-ro/chief/blob/main/backend/src/sync/persist/sync-persist.service.ts"
click node_briefing "https://github.com/clarke-ro/chief/blob/main/backend/src/briefing/briefing.service.ts"
click node_relevance "https://github.com/clarke-ro/chief/blob/main/backend/src/briefing/relevance.scorer.ts"
click node_knowledge "https://github.com/clarke-ro/chief/blob/main/backend/src/knowledge/knowledge-engine.service.ts"
click node_workspace_engine "https://github.com/clarke-ro/chief/blob/main/backend/src/workspace-engine/workspace-engine.service.ts"
click node_context_engine "https://github.com/clarke-ro/chief/blob/main/backend/src/context/context-engine.service.ts"
click node_reasoning "https://github.com/clarke-ro/chief/blob/main/backend/src/reasoning/reasoning.service.ts"
click node_database "https://github.com/clarke-ro/chief/blob/main/backend/src/common/prisma/prisma.service.ts"
click node_queue "https://github.com/clarke-ro/chief/blob/main/backend/src/common/bullmq/queue.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_client_auth,node_api_client,node_user toneBlue
class node_onboarding,node_home_brief,node_today_plan,node_chief_chat,node_actions,node_analytics,node_profile toneAmber
class node_integrations_api,node_oauth,node_provider_registry,node_sync_orchestrator,node_sync_pipeline,node_sync_fetch,node_sync_normalize_persist toneMint
class node_briefing,node_relevance,node_knowledge,node_workspace_engine,node_context_engine,node_reasoning toneRose
class node_database,node_queue,node_worker,node_providers toneIndigo
```

## Components

### Expo client

- [Client auth](https://github.com/clarke-ro/chief/blob/main/src/services/auth/authService.ts): `src/services/auth/authService.ts`
- [API client](https://github.com/clarke-ro/chief/blob/main/src/services/api/client.ts): `src/services/api/client.ts`

### User workflows

- [Onboarding](https://github.com/clarke-ro/chief/blob/main/src/features/onboarding/screens/ConnectAppsScreen.tsx): `src/features/onboarding/screens/ConnectAppsScreen.tsx`
- [Home brief](https://github.com/clarke-ro/chief/blob/main/src/features/brief/HomeScreen.tsx): `src/features/brief/HomeScreen.tsx`
- [Today schedule](https://github.com/clarke-ro/chief/blob/main/src/features/tasks/TasksScreen.tsx): `src/features/tasks/TasksScreen.tsx`
- [Ask Chief](https://github.com/clarke-ro/chief/blob/main/src/features/chief/ChiefScreen.tsx): `src/features/chief/ChiefScreen.tsx`
- [Contextual actions](https://github.com/clarke-ro/chief/blob/main/src/features/actions/actionRouter.ts): `src/features/actions/actionRouter.ts`
- [Analytics](https://github.com/clarke-ro/chief/blob/main/src/features/analytics/AnalyticsScreen.tsx): `src/features/analytics/AnalyticsScreen.tsx`
- [Profile and settings](https://github.com/clarke-ro/chief/blob/main/src/features/profile/ProfileScreen.tsx): `src/features/profile/ProfileScreen.tsx`

### Integrations and sync

- [Integration management](https://github.com/clarke-ro/chief/blob/main/backend/src/integrations/integrations.service.ts): `backend/src/integrations/integrations.service.ts`
- [OAuth flow](https://github.com/clarke-ro/chief/blob/main/backend/src/integrations/oauth/oauth.service.ts): `backend/src/integrations/oauth/oauth.service.ts`
- [Provider adapters](https://github.com/clarke-ro/chief/blob/main/backend/src/integrations/providers/provider.registry.ts): `backend/src/integrations/providers/provider.registry.ts`
- [Sync orchestration](https://github.com/clarke-ro/chief/blob/main/backend/src/sync/orchestrator/sync-orchestrator.service.ts): `backend/src/sync/orchestrator/sync-orchestrator.service.ts`
- [Sync pipeline](https://github.com/clarke-ro/chief/blob/main/backend/src/sync/pipeline/sync-pipeline.service.ts): `backend/src/sync/pipeline/sync-pipeline.service.ts`
- [Provider fetchers](https://github.com/clarke-ro/chief/tree/main/backend/src/sync/fetch): `backend/src/sync/fetch`
- [Normalize and persist](https://github.com/clarke-ro/chief/blob/main/backend/src/sync/persist/sync-persist.service.ts): `backend/src/sync/persist/sync-persist.service.ts`

### Workspace intelligence

- [Briefing and ranking](https://github.com/clarke-ro/chief/blob/main/backend/src/briefing/briefing.service.ts): `backend/src/briefing/briefing.service.ts`
- [Relevance scoring](https://github.com/clarke-ro/chief/blob/main/backend/src/briefing/relevance.scorer.ts): `backend/src/briefing/relevance.scorer.ts`
- [Knowledge snapshot](https://github.com/clarke-ro/chief/blob/main/backend/src/knowledge/knowledge-engine.service.ts): `backend/src/knowledge/knowledge-engine.service.ts`
- [Workspace understanding](https://github.com/clarke-ro/chief/blob/main/backend/src/workspace-engine/workspace-engine.service.ts): `backend/src/workspace-engine/workspace-engine.service.ts`
- [Chat context](https://github.com/clarke-ro/chief/blob/main/backend/src/context/context-engine.service.ts): `backend/src/context/context-engine.service.ts`
- [AI reasoning](https://github.com/clarke-ro/chief/blob/main/backend/src/reasoning/reasoning.service.ts): `backend/src/reasoning/reasoning.service.ts`

### Backend platform

- [PostgreSQL](https://github.com/clarke-ro/chief/blob/main/backend/src/common/prisma/prisma.service.ts): `backend/src/common/prisma/prisma.service.ts`
- [Redis and BullMQ](https://github.com/clarke-ro/chief/blob/main/backend/src/common/bullmq/queue.service.ts): `backend/src/common/bullmq/queue.service.ts`
- **Background worker**

### Other components

- **Chief user**
- **Connected work apps**

## Connections

- Chief user → Onboarding: connects accounts
- Onboarding → Client auth: authenticates with
- Client auth → API client: bootstraps session (evidence: `src/services/auth/authService.ts`)
- Chief user → Home brief: views priorities
- Home brief → API client: loads brief
- Chief user → Today schedule: plans day
- Today schedule → API client: refreshes schedule (evidence: `src/features/tasks/TasksScreen.tsx`)
- Chief user → Ask Chief: asks question
- Ask Chief → API client: posts chat
- Chief user → Contextual actions: chooses action
- Chief user → Analytics: reviews impact
- Chief user → Profile and settings: manages account
- API client → Integration management: calls API
- Integration management → OAuth flow: starts OAuth
- OAuth flow → Provider adapters: selects provider (evidence: `backend/src/integrations/oauth/oauth.service.ts`)
- Connected work apps → OAuth flow: authorizes access
- Provider adapters → Sync orchestration: provides adapters (evidence: `backend/src/sync/orchestrator/sync-orchestrator.service.ts`)
- Sync orchestration → Sync pipeline: dispatches resource jobs (evidence: `backend/src/sync/orchestrator/sync-orchestrator.service.ts`)
- Sync pipeline → Provider fetchers: fetches provider data (evidence: `backend/src/sync/pipeline/sync-pipeline.service.ts`)
- Sync pipeline → Normalize and persist: persists fetched batch (evidence: `backend/src/sync/pipeline/sync-pipeline.service.ts`)
- Normalize and persist → PostgreSQL: writes records
- Sync pipeline → Briefing and ranking: queues fresh brief (evidence: `backend/src/sync/pipeline/sync-pipeline.service.ts`)
- Sync orchestration → Redis and BullMQ: enqueues sync jobs (evidence: `backend/src/sync/orchestrator/sync-orchestrator.service.ts`)
- Redis and BullMQ → Background worker: delivers jobs
- Background worker → Sync pipeline: runs sync
- Briefing and ranking → Relevance scoring: ranks candidates (evidence: `backend/src/briefing/briefing.service.ts`)
- Briefing and ranking → PostgreSQL: reads workspace data (evidence: `backend/src/briefing/briefing.service.ts`)
- Knowledge snapshot → PostgreSQL: loads snapshot (evidence: `backend/src/knowledge/knowledge-engine.service.ts`)
- Workspace understanding → Briefing and ranking: builds on brief (evidence: `backend/src/workspace-engine/workspace-engine.service.ts`)
- Workspace understanding → Knowledge snapshot: loads knowledge (evidence: `backend/src/workspace-engine/workspace-engine.service.ts`)
- Ask Chief → Chat context: requests context
- Chat context → Workspace understanding: builds workspace snapshot (evidence: `backend/src/context/context-engine.service.ts`)
- Chat context → AI reasoning: supplies structured context
- AI reasoning → Ask Chief: returns reply