# ikdevv/cadence architecture

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

- Interactive diagram: https://gitdiagram.com/ikdevv/cadence
- Repository: https://github.com/ikdevv/cadence

## Overview

Cadence is a weekly team-reporting product: members create and submit structured reports, managers review them and either approve or request corrections, and managers track team activity and analytics. The web app reaches a NestJS API backed by PostgreSQL. Additional branches cover authentication, invitations and user administration, projects, and an AI assistant for manager questions. Edges are limited to relationships shown in sampled source, the source index, or README; several web-to-API links and unsampled capabilities rely on README documentation.

Main entry points: [`apps/web/lib/api/client.ts`](https://github.com/ikdevv/cadence/blob/main/apps/web/lib/api/client.ts) (Web API client), [`apps/api/src/modules/assistant/assistant-context.service.ts`](https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/assistant/assistant-context.service.ts) (Assistant context), [`apps/api/src/modules/reports/reports.service.ts`](https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/reports/reports.service.ts) (Report authoring), [`apps/api/src/modules/assistant/assistant.service.ts`](https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/assistant/assistant.service.ts) (Report assistant)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web app"]
  node_report_pages["Report pages<br/>[page.tsx]"]
  node_review_page["Review page<br/>[page.tsx]"]
  node_team_page["Team dashboard<br/>[page.tsx]"]
  node_analytics_page["Analytics page<br/>[page.tsx]"]
  node_admin_page["User administration<br/>[page.tsx]"]
  node_project_page["Project management<br/>[page.tsx]"]
  node_web_api["Web API client<br/>[client.ts]"]
end

subgraph group_identity["Identity and administration"]
  node_auth["Authentication<br/>[auth.service.ts]"]
  node_users["User management<br/>[users.service.ts]"]
  node_invitations["Invitations"]
  node_email["Invitation email<br/>[email.service.ts]"]
end

subgraph group_reporting["Reports and review"]
  node_projects["Project management API"]
  node_reports["Report authoring<br/>[reports.service.ts]"]
  node_versions["Report versions"]
  node_reviews["Review workflow<br/>[reviews.service.ts]"]
  node_team_reports["Team report queries"]
end

subgraph group_insights["Team insights"]
  node_analytics["Team analytics"]
  node_assistant["Report assistant"]
  node_assistant_context["Assistant context"]
  node_ai_provider["Hugging Face provider"]
end

subgraph group_data["Data and integrations"]
  node_postgres[("PostgreSQL")]
end

node_member(("Team member"))
node_manager(("Manager"))
node_admin(("Administrator"))

node_member -->|"files reports"| node_report_pages
node_manager -->|"reviews reports"| node_review_page
node_manager -->|"views dashboard"| node_team_page
node_manager -->|"views analytics"| node_analytics_page
node_admin -->|"manages users"| node_admin_page
node_manager -->|"manages projects"| node_project_page
node_report_pages -->|"requests data"| node_web_api
node_review_page -->|"requests reviews"| node_web_api
node_team_page -->|"requests team data"| node_web_api
node_analytics_page -->|"requests analytics"| node_web_api
node_admin_page -->|"requests admin actions"| node_web_api
node_project_page -->|"requests projects"| node_web_api
node_web_api -.->|"calls API"| node_auth
node_web_api -.->|"calls API"| node_reports
node_web_api -.->|"calls API"| node_reviews
node_web_api -.->|"calls API"| node_analytics
node_web_api -.->|"calls API"| node_users
node_web_api -.->|"calls API"| node_invitations
node_web_api -.->|"calls API"| node_projects
node_reports -->|"uses versions"| node_versions
node_reviews -->|"clones versions"| node_versions
node_team_page -->|"views team reports"| node_team_reports
node_assistant -->|"builds context"| node_assistant_context
node_assistant -->|"generates response"| node_ai_provider
node_assistant_context -->|"reads analytics"| node_analytics
node_assistant_context -->|"reads report details"| node_reports
node_assistant_context -->|"lists team reports"| node_team_reports
node_assistant -->|"answers questions"| node_manager
node_invitations -->|"sends invitations"| node_email
node_auth -->|"looks up users"| node_users
node_auth -->|"reads and writes tokens"| node_postgres
node_users -->|"reads and writes users"| node_postgres
node_reports -->|"reads and writes reports"| node_postgres
node_reviews -->|"writes review actions"| node_postgres
node_analytics -->|"queries team data"| node_postgres
node_invitations -->|"stores invitations"| node_postgres
node_projects -.->|"stores projects"| node_postgres

click node_report_pages "https://github.com/ikdevv/cadence/blob/main/apps/web/app/(app)/reports/page.tsx"
click node_review_page "https://github.com/ikdevv/cadence/blob/main/apps/web/app/(app)/team/reports/%5Bid%5D/review/page.tsx"
click node_team_page "https://github.com/ikdevv/cadence/blob/main/apps/web/app/(app)/team/page.tsx"
click node_analytics_page "https://github.com/ikdevv/cadence/blob/main/apps/web/app/(app)/analytics/page.tsx"
click node_admin_page "https://github.com/ikdevv/cadence/blob/main/apps/web/app/(app)/admin/users/page.tsx"
click node_project_page "https://github.com/ikdevv/cadence/blob/main/apps/web/app/(app)/projects/page.tsx"
click node_web_api "https://github.com/ikdevv/cadence/blob/main/apps/web/lib/api/client.ts"
click node_auth "https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/auth/auth.service.ts"
click node_users "https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/users/users.service.ts"
click node_invitations "https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/invitations/invitations.service.ts"
click node_email "https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/email/email.service.ts"
click node_projects "https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/projects/projects.service.ts"
click node_reports "https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/reports/reports.service.ts"
click node_versions "https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/reports/report-versions.service.ts"
click node_reviews "https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/reviews/reviews.service.ts"
click node_team_reports "https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/reviews/team-reports.service.ts"
click node_analytics "https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/analytics/analytics.service.ts"
click node_assistant "https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/assistant/assistant.service.ts"
click node_assistant_context "https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/assistant/assistant-context.service.ts"
click node_ai_provider "https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/assistant/ai/huggingface.provider.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_report_pages,node_review_page,node_team_page,node_analytics_page,node_admin_page,node_project_page,node_web_api toneBlue
class node_auth,node_users,node_invitations,node_email toneAmber
class node_projects,node_reports,node_versions,node_reviews,node_team_reports toneMint
class node_analytics,node_assistant,node_assistant_context,node_ai_provider toneRose
class node_postgres,node_member,node_manager,node_admin toneIndigo
```

## Components

### Web app

- [Report pages](https://github.com/ikdevv/cadence/blob/main/apps/web/app/(app)/reports/page.tsx): `apps/web/app/(app)/reports/page.tsx`
- [Review page](https://github.com/ikdevv/cadence/blob/main/apps/web/app/(app)/team/reports/%5Bid%5D/review/page.tsx): `apps/web/app/(app)/team/reports/[id]/review/page.tsx`
- [Team dashboard](https://github.com/ikdevv/cadence/blob/main/apps/web/app/(app)/team/page.tsx): `apps/web/app/(app)/team/page.tsx`
- [Analytics page](https://github.com/ikdevv/cadence/blob/main/apps/web/app/(app)/analytics/page.tsx): `apps/web/app/(app)/analytics/page.tsx`
- [User administration](https://github.com/ikdevv/cadence/blob/main/apps/web/app/(app)/admin/users/page.tsx): `apps/web/app/(app)/admin/users/page.tsx`
- [Project management](https://github.com/ikdevv/cadence/blob/main/apps/web/app/(app)/projects/page.tsx): `apps/web/app/(app)/projects/page.tsx`
- [Web API client](https://github.com/ikdevv/cadence/blob/main/apps/web/lib/api/client.ts): `apps/web/lib/api/client.ts`

### Identity and administration

- [Authentication](https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/auth/auth.service.ts): `apps/api/src/modules/auth/auth.service.ts`
- [User management](https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/users/users.service.ts): `apps/api/src/modules/users/users.service.ts`
- [Invitations](https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/invitations/invitations.service.ts): `apps/api/src/modules/invitations/invitations.service.ts`
- [Invitation email](https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/email/email.service.ts): `apps/api/src/modules/email/email.service.ts`

### Reports and review

- [Project management API](https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/projects/projects.service.ts): `apps/api/src/modules/projects/projects.service.ts`
- [Report authoring](https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/reports/reports.service.ts): `apps/api/src/modules/reports/reports.service.ts`
- [Report versions](https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/reports/report-versions.service.ts): `apps/api/src/modules/reports/report-versions.service.ts`
- [Review workflow](https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/reviews/reviews.service.ts): `apps/api/src/modules/reviews/reviews.service.ts`
- [Team report queries](https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/reviews/team-reports.service.ts): `apps/api/src/modules/reviews/team-reports.service.ts`

### Team insights

- [Team analytics](https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/analytics/analytics.service.ts): `apps/api/src/modules/analytics/analytics.service.ts`
- [Report assistant](https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/assistant/assistant.service.ts): `apps/api/src/modules/assistant/assistant.service.ts`
- [Assistant context](https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/assistant/assistant-context.service.ts): `apps/api/src/modules/assistant/assistant-context.service.ts`
- [Hugging Face provider](https://github.com/ikdevv/cadence/blob/main/apps/api/src/modules/assistant/ai/huggingface.provider.ts): `apps/api/src/modules/assistant/ai/huggingface.provider.ts`

### Data and integrations

- **PostgreSQL**

### Other components

- **Team member**
- **Manager**
- **Administrator**

## Connections

- Team member → Report pages: files reports
- Manager → Review page: reviews reports
- Manager → Team dashboard: views dashboard
- Manager → Analytics page: views analytics
- Administrator → User administration: manages users
- Manager → Project management: manages projects
- Report pages → Web API client: requests data
- Review page → Web API client: requests reviews
- Team dashboard → Web API client: requests team data
- Analytics page → Web API client: requests analytics
- User administration → Web API client: requests admin actions
- Project management → Web API client: requests projects
- Web API client → Authentication: calls API
- Web API client → Report authoring: calls API
- Web API client → Review workflow: calls API
- Web API client → Team analytics: calls API
- Web API client → User management: calls API
- Web API client → Invitations: calls API
- Web API client → Project management API: calls API
- Report authoring → Report versions: uses versions (evidence: `apps/api/src/modules/reports/reports.service.ts`)
- Review workflow → Report versions: clones versions (evidence: `apps/api/src/modules/reviews/reviews.service.ts`)
- Team dashboard → Team report queries: views team reports
- Report assistant → Assistant context: builds context (evidence: `apps/api/src/modules/assistant/assistant.service.ts`)
- Report assistant → Hugging Face provider: generates response (evidence: `apps/api/src/modules/assistant/assistant.service.ts`)
- Assistant context → Team analytics: reads analytics (evidence: `apps/api/src/modules/assistant/assistant-context.service.ts`)
- Assistant context → Report authoring: reads report details (evidence: `apps/api/src/modules/assistant/assistant-context.service.ts`)
- Assistant context → Team report queries: lists team reports (evidence: `apps/api/src/modules/assistant/assistant-context.service.ts`)
- Report assistant → Manager: answers questions
- Invitations → Invitation email: sends invitations (evidence: `apps/api/src/modules/invitations/invitations.service.ts`)
- Authentication → User management: looks up users (evidence: `apps/api/src/modules/auth/auth.service.ts`)
- Authentication → PostgreSQL: reads and writes tokens (evidence: `apps/api/src/modules/auth/auth.service.ts`)
- User management → PostgreSQL: reads and writes users (evidence: `apps/api/src/modules/users/users.service.ts`)
- Report authoring → PostgreSQL: reads and writes reports (evidence: `apps/api/src/modules/reports/reports.service.ts`)
- Review workflow → PostgreSQL: writes review actions (evidence: `apps/api/src/modules/reviews/reviews.service.ts`)
- Team analytics → PostgreSQL: queries team data (evidence: `apps/api/src/modules/analytics/analytics.service.ts`)
- Invitations → PostgreSQL: stores invitations (evidence: `apps/api/src/modules/invitations/invitations.service.ts`)
- Project management API → PostgreSQL: stores projects
