# krutarth3238/crewmate architecture

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

- Interactive diagram: https://gitdiagram.com/krutarth3238/crewmate
- Repository: https://github.com/krutarth3238/crewmate

## Overview

Crewmate is a gamified AI co-founder console: a founder signs in, sets up a workspace and teammate, connects Google, then uses the console to submit missions and review outcomes. The backend plans and executes agent tasks, gates restricted actions for approval, records missions, and awards XP through a server-authoritative trust engine. The README documents simulated Google Workspace tools and the major product capabilities; source-index references and excerpts support the specific internal links shown. Unsampled implementation details are omitted where their connections are not established.

Main entry points: [`backend/app/database.py`](https://github.com/krutarth3238/crewmate/blob/main/backend/app/database.py) (SQL database), [`backend/app/main.py`](https://github.com/krutarth3238/crewmate/blob/main/backend/app/main.py) (FastAPI app), [`backend/app/agent/engine.py`](https://github.com/krutarth3238/crewmate/blob/main/backend/app/agent/engine.py) (Execution engine), [`frontend/src/App.tsx`](https://github.com/krutarth3238/crewmate/blob/main/frontend/src/App.tsx) (App views)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_console["Console and identity"]
  node_app["App views<br/>[App.tsx]"]
  node_authctx["Auth context<br/>[AuthContext.tsx]"]
  node_consoleui["Gamified console<br/>[Console.tsx]"]
  node_onboarding["Workspace setup"]
  node_googleview["Google connect"]
  node_apiclient["API client<br/>[api.ts]"]
end

subgraph group_domain["Workspace and progression"]
  node_workspaceapi["Workspace API<br/>[router.py]"]
  node_workspaces["Workspace service<br/>[service.py]"]
  node_teammateapi["Teammate API<br/>[router.py]"]
  node_trust["Trust engine<br/>[service.py]"]
  node_missions["Mission audit API<br/>[router.py]"]
  node_skills["Skill catalog<br/>[router.py]"]
end

subgraph group_execution["Agent and approvals"]
  node_agentapi["Agent API<br/>[router.py]"]
  node_engine["Execution engine<br/>[engine.py]"]
  node_tools["Simulated tools<br/>[tools.py]"]
  node_questapi["Approval API<br/>[router.py]"]
  node_questservice["Approval service<br/>[service.py]"]
end

subgraph group_platform["API and persistence"]
  node_authapi["Account API<br/>[router.py]"]
  node_googleoauth["Google OAuth<br/>[router.py]"]
  node_apiapp["FastAPI app<br/>[main.py]"]
  node_authguard["Auth guard<br/>[auth_guard.py]"]
  node_database[("SQL database<br/>[database.py]")]
  node_models["Domain records"]
end

node_founder(("Founder"))
node_firebase{{"Firebase Auth"}}
node_groq{{"Groq inference"}}

node_founder -->|"uses console"| node_app
node_app -->|"reads auth state"| node_authctx
node_app -->|"shows workspace"| node_consoleui
node_app -->|"starts setup"| node_onboarding
node_app -->|"shows connection"| node_googleview
node_authctx -->|"subscribes to auth"| node_firebase
node_authctx -->|"syncs identity"| node_apiclient
node_consoleui -->|"calls API"| node_apiclient
node_onboarding -->|"submits setup"| node_apiclient
node_googleview -.->|"starts OAuth"| node_apiclient
node_apiclient -->|"sends requests"| node_apiapp
node_apiapp -->|"dispatches auth"| node_authapi
node_apiapp -->|"dispatches workspace"| node_workspaceapi
node_apiapp -->|"dispatches teammate"| node_teammateapi
node_apiapp -->|"dispatches missions"| node_missions
node_apiapp -->|"dispatches skills"| node_skills
node_apiapp -->|"dispatches agent"| node_agentapi
node_apiapp -->|"dispatches approvals"| node_questapi
node_apiapp -->|"dispatches OAuth"| node_googleoauth
node_workspaceapi -->|"delegates to"| node_workspaces
node_teammateapi -->|"uses progression"| node_trust
node_agentapi -->|"invokes execution"| node_engine
node_engine -->|"runs tool steps"| node_tools
node_engine -.->|"plans with"| node_groq
node_engine -->|"awards XP"| node_trust
node_engine -.->|"creates approvals"| node_questservice
node_questapi -->|"handles resolution"| node_questservice
node_questservice -->|"executes approved plan"| node_tools
node_questservice -->|"awards XP"| node_trust
node_authguard -->|"verifies tokens"| node_firebase
node_authapi -->|"uses identity"| node_authguard
node_googleoauth -->|"stores tokens"| node_database
node_googleoauth -->|"requires identity"| node_authguard
node_database -->|"maps records"| node_models
node_missions -->|"reads missions"| node_database
node_skills -->|"reads and updates"| node_database
node_workspaceapi -->|"uses sessions"| node_database
node_teammateapi -->|"uses sessions"| node_database
node_agentapi -->|"uses sessions"| node_database
node_questapi -->|"uses sessions"| node_database
node_authapi -->|"uses sessions"| node_database
node_engine -.->|"records run and mission"| node_database
node_questservice -.->|"records approvals"| node_database

click node_app "https://github.com/krutarth3238/crewmate/blob/main/frontend/src/App.tsx"
click node_authctx "https://github.com/krutarth3238/crewmate/blob/main/frontend/src/context/AuthContext.tsx"
click node_consoleui "https://github.com/krutarth3238/crewmate/blob/main/frontend/src/components/Console.tsx"
click node_onboarding "https://github.com/krutarth3238/crewmate/blob/main/frontend/src/components/OnboardingModal.tsx"
click node_googleview "https://github.com/krutarth3238/crewmate/blob/main/frontend/src/components/GoogleConnectView.tsx"
click node_apiclient "https://github.com/krutarth3238/crewmate/blob/main/frontend/src/lib/api.ts"
click node_authapi "https://github.com/krutarth3238/crewmate/blob/main/backend/app/auth/router.py"
click node_workspaceapi "https://github.com/krutarth3238/crewmate/blob/main/backend/app/workspaces/router.py"
click node_workspaces "https://github.com/krutarth3238/crewmate/blob/main/backend/app/workspaces/service.py"
click node_teammateapi "https://github.com/krutarth3238/crewmate/blob/main/backend/app/teammates/router.py"
click node_trust "https://github.com/krutarth3238/crewmate/blob/main/backend/app/teammates/service.py"
click node_missions "https://github.com/krutarth3238/crewmate/blob/main/backend/app/missions/router.py"
click node_skills "https://github.com/krutarth3238/crewmate/blob/main/backend/app/skills/router.py"
click node_agentapi "https://github.com/krutarth3238/crewmate/blob/main/backend/app/agent/router.py"
click node_engine "https://github.com/krutarth3238/crewmate/blob/main/backend/app/agent/engine.py"
click node_tools "https://github.com/krutarth3238/crewmate/blob/main/backend/app/agent/tools.py"
click node_questapi "https://github.com/krutarth3238/crewmate/blob/main/backend/app/quests/router.py"
click node_questservice "https://github.com/krutarth3238/crewmate/blob/main/backend/app/quests/service.py"
click node_googleoauth "https://github.com/krutarth3238/crewmate/blob/main/backend/app/google_oauth/router.py"
click node_apiapp "https://github.com/krutarth3238/crewmate/blob/main/backend/app/main.py"
click node_authguard "https://github.com/krutarth3238/crewmate/blob/main/backend/app/middleware/auth_guard.py"
click node_database "https://github.com/krutarth3238/crewmate/blob/main/backend/app/database.py"
click node_models "https://github.com/krutarth3238/crewmate/tree/main/backend/app/models"

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_app,node_authctx,node_consoleui,node_onboarding,node_googleview,node_apiclient toneBlue
class node_workspaceapi,node_workspaces,node_teammateapi,node_trust,node_missions,node_skills toneAmber
class node_agentapi,node_engine,node_tools,node_questapi,node_questservice toneMint
class node_authapi,node_googleoauth,node_apiapp,node_authguard,node_database,node_models toneRose
class node_founder,node_firebase,node_groq toneIndigo
```

## Components

### Console and identity

- [App views](https://github.com/krutarth3238/crewmate/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Auth context](https://github.com/krutarth3238/crewmate/blob/main/frontend/src/context/AuthContext.tsx): `frontend/src/context/AuthContext.tsx`
- [Gamified console](https://github.com/krutarth3238/crewmate/blob/main/frontend/src/components/Console.tsx): `frontend/src/components/Console.tsx`
- [Workspace setup](https://github.com/krutarth3238/crewmate/blob/main/frontend/src/components/OnboardingModal.tsx): `frontend/src/components/OnboardingModal.tsx`
- [Google connect](https://github.com/krutarth3238/crewmate/blob/main/frontend/src/components/GoogleConnectView.tsx): `frontend/src/components/GoogleConnectView.tsx`
- [API client](https://github.com/krutarth3238/crewmate/blob/main/frontend/src/lib/api.ts): `frontend/src/lib/api.ts`

### Workspace and progression

- [Workspace API](https://github.com/krutarth3238/crewmate/blob/main/backend/app/workspaces/router.py): `backend/app/workspaces/router.py`
- [Workspace service](https://github.com/krutarth3238/crewmate/blob/main/backend/app/workspaces/service.py): `backend/app/workspaces/service.py`
- [Teammate API](https://github.com/krutarth3238/crewmate/blob/main/backend/app/teammates/router.py): `backend/app/teammates/router.py`
- [Trust engine](https://github.com/krutarth3238/crewmate/blob/main/backend/app/teammates/service.py): `backend/app/teammates/service.py`
- [Mission audit API](https://github.com/krutarth3238/crewmate/blob/main/backend/app/missions/router.py): `backend/app/missions/router.py`
- [Skill catalog](https://github.com/krutarth3238/crewmate/blob/main/backend/app/skills/router.py): `backend/app/skills/router.py`

### Agent and approvals

- [Agent API](https://github.com/krutarth3238/crewmate/blob/main/backend/app/agent/router.py): `backend/app/agent/router.py`
- [Execution engine](https://github.com/krutarth3238/crewmate/blob/main/backend/app/agent/engine.py): `backend/app/agent/engine.py`
- [Simulated tools](https://github.com/krutarth3238/crewmate/blob/main/backend/app/agent/tools.py): `backend/app/agent/tools.py`
- [Approval API](https://github.com/krutarth3238/crewmate/blob/main/backend/app/quests/router.py): `backend/app/quests/router.py`
- [Approval service](https://github.com/krutarth3238/crewmate/blob/main/backend/app/quests/service.py): `backend/app/quests/service.py`

### API and persistence

- [Account API](https://github.com/krutarth3238/crewmate/blob/main/backend/app/auth/router.py): `backend/app/auth/router.py`
- [Google OAuth](https://github.com/krutarth3238/crewmate/blob/main/backend/app/google_oauth/router.py): `backend/app/google_oauth/router.py`
- [FastAPI app](https://github.com/krutarth3238/crewmate/blob/main/backend/app/main.py): `backend/app/main.py`
- [Auth guard](https://github.com/krutarth3238/crewmate/blob/main/backend/app/middleware/auth_guard.py): `backend/app/middleware/auth_guard.py`
- [SQL database](https://github.com/krutarth3238/crewmate/blob/main/backend/app/database.py): `backend/app/database.py`
- [Domain records](https://github.com/krutarth3238/crewmate/tree/main/backend/app/models): `backend/app/models`

### Other components

- **Founder**
- **Firebase Auth**
- **Groq inference**

## Connections

- Founder → App views: uses console
- App views → Auth context: reads auth state (evidence: `frontend/src/App.tsx`)
- App views → Gamified console: shows workspace (evidence: `frontend/src/App.tsx`)
- App views → Workspace setup: starts setup (evidence: `frontend/src/App.tsx`)
- App views → Google connect: shows connection (evidence: `frontend/src/App.tsx`)
- Auth context → Firebase Auth: subscribes to auth (evidence: `frontend/src/context/AuthContext.tsx`)
- Auth context → API client: syncs identity (evidence: `frontend/src/context/AuthContext.tsx`)
- Gamified console → API client: calls API (evidence: `frontend/src/components/Console.tsx`)
- Workspace setup → API client: submits setup (evidence: `frontend/src/components/OnboardingModal.tsx`)
- Google connect → API client: starts OAuth
- API client → FastAPI app: sends requests
- FastAPI app → Account API: dispatches auth (evidence: `backend/app/main.py`)
- FastAPI app → Workspace API: dispatches workspace (evidence: `backend/app/main.py`)
- FastAPI app → Teammate API: dispatches teammate (evidence: `backend/app/main.py`)
- FastAPI app → Mission audit API: dispatches missions (evidence: `backend/app/main.py`)
- FastAPI app → Skill catalog: dispatches skills (evidence: `backend/app/main.py`)
- FastAPI app → Agent API: dispatches agent (evidence: `backend/app/main.py`)
- FastAPI app → Approval API: dispatches approvals (evidence: `backend/app/main.py`)
- FastAPI app → Google OAuth: dispatches OAuth (evidence: `backend/app/main.py`)
- Workspace API → Workspace service: delegates to (evidence: `backend/app/workspaces/router.py`)
- Teammate API → Trust engine: uses progression (evidence: `backend/app/teammates/router.py`)
- Agent API → Execution engine: invokes execution (evidence: `backend/app/agent/router.py`)
- Execution engine → Simulated tools: runs tool steps (evidence: `backend/app/agent/engine.py`)
- Execution engine → Groq inference: plans with
- Execution engine → Trust engine: awards XP (evidence: `backend/app/agent/engine.py`)
- Execution engine → Approval service: creates approvals
- Approval API → Approval service: handles resolution (evidence: `backend/app/quests/router.py`)
- Approval service → Simulated tools: executes approved plan (evidence: `backend/app/quests/service.py`)
- Approval service → Trust engine: awards XP (evidence: `backend/app/quests/service.py`)
- Auth guard → Firebase Auth: verifies tokens (evidence: `backend/app/middleware/auth_guard.py`)
- Account API → Auth guard: uses identity (evidence: `backend/app/auth/router.py`)
- Google OAuth → SQL database: stores tokens (evidence: `backend/app/google_oauth/router.py`)
- Google OAuth → Auth guard: requires identity (evidence: `backend/app/google_oauth/router.py`)
- SQL database → Domain records: maps records (evidence: `backend/app/database.py`)
- Mission audit API → SQL database: reads missions (evidence: `backend/app/missions/router.py`)
- Skill catalog → SQL database: reads and updates (evidence: `backend/app/skills/router.py`)
- Workspace API → SQL database: uses sessions (evidence: `backend/app/workspaces/router.py`)
- Teammate API → SQL database: uses sessions (evidence: `backend/app/teammates/router.py`)
- Agent API → SQL database: uses sessions (evidence: `backend/app/agent/router.py`)
- Approval API → SQL database: uses sessions (evidence: `backend/app/quests/router.py`)
- Account API → SQL database: uses sessions (evidence: `backend/app/auth/router.py`)
- Execution engine → SQL database: records run and mission
- Approval service → SQL database: records approvals