# datakitpage/datakit architecture

> Architecture diagram of the GitHub repository datakitpage/datakit, 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/datakitpage/datakit
- Repository: https://github.com/datakitpage/datakit

## Overview

DataKit is a browser-based data analysis studio: users import local or remote datasets, then inspect, query, analyze with AI, or work in Python notebooks. The README describes processing as local to the browser unless users explicitly connect cloud services. The graph includes the documented analysis capabilities and sampled backend account, workspace, credit, and PostgreSQL-proxy services. Frontend internals were mostly not sampled, so their feature relationships are documented at the capability level rather than inferred as specific calls.

Main entry points: [`frontend/src/App.tsx`](https://github.com/datakitpage/datakit/blob/main/frontend/src/App.tsx) (Studio shell), [`backend/api/src/auth/auth.service.ts`](https://github.com/datakitpage/datakit/blob/main/backend/api/src/auth/auth.service.ts) (Authentication), [`backend/api/src/auth/auth.controller.ts`](https://github.com/datakitpage/datakit/blob/main/backend/api/src/auth/auth.controller.ts) (Auth endpoints), [`backend/api/src/subscriptions/subscriptions.service.ts`](https://github.com/datakitpage/datakit/blob/main/backend/api/src/subscriptions/subscriptions.service.ts) (Plans and billing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Studio experience"]
  node_studio["Studio shell<br/>[App.tsx]"]
end

subgraph group_data["Data workflows"]
  node_import["Dataset import"]
  node_remote["Remote connectors"]
  node_ingest["Local data engine"]
end

subgraph group_analysis["Analysis tools"]
  node_preview["Grid and inspection"]
  node_inspector["Quality analysis<br/>[inspector.ts]"]
  node_query["SQL workspace"]
  node_queryengine["DuckDB queries<br/>[query.ts]"]
  node_assistant["AI assistant<br/>[aiService.ts]"]
  node_notebooks["Python notebooks<br/>[executor.ts]"]
end

subgraph group_identity["Identity and teams"]
  node_authcontroller["Auth endpoints<br/>[auth.controller.ts]"]
  node_authservice["Authentication<br/>[auth.service.ts]"]
  node_users[("User accounts<br/>[user.entity.ts]")]
  node_userops["User operations<br/>[users.service.ts]"]
  node_workspaces[("Workspace records")]
  node_members[("Team membership")]
  node_workspaceops["Workspace operations"]
end

subgraph group_services["Platform services"]
  node_api["Application API<br/>[main.ts]"]
  node_subscriptions["Plans and billing"]
  node_subscriptiondata[("Subscription records")]
  node_credits["Credit accounting<br/>[credits.service.ts]"]
  node_creditdata[("Usage records")]
  node_pgcontroller["Postgres endpoints"]
  node_pgproxy["Postgres proxy"]
end

node_user(("Data analyst"))
node_pgdatabase[("Connected PostgreSQL")]

node_user -->|"uses"| node_studio
node_studio -->|"starts import"| node_import
node_import -->|"loads locally"| node_ingest
node_remote -.->|"imports data"| node_ingest
node_studio -->|"opens preview"| node_preview
node_preview -->|"analyzes data"| node_inspector
node_studio -->|"opens SQL"| node_query
node_query -->|"runs SQL"| node_queryengine
node_studio -->|"asks questions"| node_assistant
node_studio -->|"opens notebooks"| node_notebooks
node_user -->|"signs in"| node_authcontroller
node_authcontroller -->|"handles auth"| node_authservice
node_authservice -->|"looks up users"| node_userops
node_authservice -->|"creates plan"| node_subscriptions
node_authservice -->|"creates workspace"| node_workspaceops
node_authcontroller -->|"returns profile"| node_users
node_workspaceops -.->|"manages members"| node_members
node_subscriptions -.->|"persists plans"| node_subscriptiondata
node_credits -->|"records usage"| node_creditdata
node_credits -->|"checks allowance"| node_subscriptions
node_pgcontroller -->|"routes requests"| node_pgproxy
node_pgproxy -.->|"queries database"| node_pgdatabase

click node_studio "https://github.com/datakitpage/datakit/blob/main/frontend/src/App.tsx"
click node_import "https://github.com/datakitpage/datakit/blob/main/frontend/src/hooks/useDirectFileImport.ts"
click node_remote "https://github.com/datakitpage/datakit/tree/main/frontend/src/hooks/remote"
click node_ingest "https://github.com/datakitpage/datakit/tree/main/frontend/src/lib/duckdb/ingestion"
click node_preview "https://github.com/datakitpage/datakit/tree/main/frontend/src/components/data-grid"
click node_inspector "https://github.com/datakitpage/datakit/blob/main/frontend/src/lib/duckdb/inspector/inspector.ts"
click node_query "https://github.com/datakitpage/datakit/blob/main/frontend/src/hooks/query/useQueryExecution.ts"
click node_queryengine "https://github.com/datakitpage/datakit/blob/main/frontend/src/lib/duckdb/query.ts"
click node_assistant "https://github.com/datakitpage/datakit/blob/main/frontend/src/lib/ai/aiService.ts"
click node_notebooks "https://github.com/datakitpage/datakit/blob/main/frontend/src/lib/python/executor.ts"
click node_api "https://github.com/datakitpage/datakit/blob/main/backend/api/src/main.ts"
click node_authcontroller "https://github.com/datakitpage/datakit/blob/main/backend/api/src/auth/auth.controller.ts"
click node_authservice "https://github.com/datakitpage/datakit/blob/main/backend/api/src/auth/auth.service.ts"
click node_users "https://github.com/datakitpage/datakit/blob/main/backend/api/src/users/entities/user.entity.ts"
click node_userops "https://github.com/datakitpage/datakit/blob/main/backend/api/src/users/users.service.ts"
click node_workspaces "https://github.com/datakitpage/datakit/blob/main/backend/api/src/workspaces/entities/workspace.entity.ts"
click node_members "https://github.com/datakitpage/datakit/blob/main/backend/api/src/workspaces/entities/workspace-member.entity.ts"
click node_workspaceops "https://github.com/datakitpage/datakit/blob/main/backend/api/src/workspaces/workspaces.service.ts"
click node_subscriptions "https://github.com/datakitpage/datakit/blob/main/backend/api/src/subscriptions/subscriptions.service.ts"
click node_subscriptiondata "https://github.com/datakitpage/datakit/blob/main/backend/api/src/subscriptions/entities/subscription.entity.ts"
click node_credits "https://github.com/datakitpage/datakit/blob/main/backend/api/src/credits/credits.service.ts"
click node_creditdata "https://github.com/datakitpage/datakit/blob/main/backend/api/src/credits/entities/credit-usage.entity.ts"
click node_pgcontroller "https://github.com/datakitpage/datakit/blob/main/backend/api/src/postgres-proxy/postgres-proxy.controller.ts"
click node_pgproxy "https://github.com/datakitpage/datakit/blob/main/backend/api/src/postgres-proxy/postgres-proxy.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_studio toneBlue
class node_import,node_remote,node_ingest,node_pgdatabase toneAmber
class node_preview,node_inspector,node_query,node_queryengine,node_assistant,node_notebooks toneMint
class node_authcontroller,node_authservice,node_users,node_userops,node_workspaces,node_members,node_workspaceops toneRose
class node_api,node_subscriptions,node_subscriptiondata,node_credits,node_creditdata,node_pgcontroller,node_pgproxy,node_user toneIndigo
```

## Components

### Studio experience

- [Studio shell](https://github.com/datakitpage/datakit/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`

### Data workflows

- [Dataset import](https://github.com/datakitpage/datakit/blob/main/frontend/src/hooks/useDirectFileImport.ts): `frontend/src/hooks/useDirectFileImport.ts`
- [Remote connectors](https://github.com/datakitpage/datakit/tree/main/frontend/src/hooks/remote): `frontend/src/hooks/remote`
- [Local data engine](https://github.com/datakitpage/datakit/tree/main/frontend/src/lib/duckdb/ingestion): `frontend/src/lib/duckdb/ingestion`

### Analysis tools

- [Grid and inspection](https://github.com/datakitpage/datakit/tree/main/frontend/src/components/data-grid): `frontend/src/components/data-grid`
- [Quality analysis](https://github.com/datakitpage/datakit/blob/main/frontend/src/lib/duckdb/inspector/inspector.ts): `frontend/src/lib/duckdb/inspector/inspector.ts`
- [SQL workspace](https://github.com/datakitpage/datakit/blob/main/frontend/src/hooks/query/useQueryExecution.ts): `frontend/src/hooks/query/useQueryExecution.ts`
- [DuckDB queries](https://github.com/datakitpage/datakit/blob/main/frontend/src/lib/duckdb/query.ts): `frontend/src/lib/duckdb/query.ts`
- [AI assistant](https://github.com/datakitpage/datakit/blob/main/frontend/src/lib/ai/aiService.ts): `frontend/src/lib/ai/aiService.ts`
- [Python notebooks](https://github.com/datakitpage/datakit/blob/main/frontend/src/lib/python/executor.ts): `frontend/src/lib/python/executor.ts`

### Identity and teams

- [Auth endpoints](https://github.com/datakitpage/datakit/blob/main/backend/api/src/auth/auth.controller.ts): `backend/api/src/auth/auth.controller.ts`
- [Authentication](https://github.com/datakitpage/datakit/blob/main/backend/api/src/auth/auth.service.ts): `backend/api/src/auth/auth.service.ts`
- [User accounts](https://github.com/datakitpage/datakit/blob/main/backend/api/src/users/entities/user.entity.ts): `backend/api/src/users/entities/user.entity.ts`
- [User operations](https://github.com/datakitpage/datakit/blob/main/backend/api/src/users/users.service.ts): `backend/api/src/users/users.service.ts`
- [Workspace records](https://github.com/datakitpage/datakit/blob/main/backend/api/src/workspaces/entities/workspace.entity.ts): `backend/api/src/workspaces/entities/workspace.entity.ts`
- [Team membership](https://github.com/datakitpage/datakit/blob/main/backend/api/src/workspaces/entities/workspace-member.entity.ts): `backend/api/src/workspaces/entities/workspace-member.entity.ts`
- [Workspace operations](https://github.com/datakitpage/datakit/blob/main/backend/api/src/workspaces/workspaces.service.ts): `backend/api/src/workspaces/workspaces.service.ts`

### Platform services

- [Application API](https://github.com/datakitpage/datakit/blob/main/backend/api/src/main.ts): `backend/api/src/main.ts`
- [Plans and billing](https://github.com/datakitpage/datakit/blob/main/backend/api/src/subscriptions/subscriptions.service.ts): `backend/api/src/subscriptions/subscriptions.service.ts`
- [Subscription records](https://github.com/datakitpage/datakit/blob/main/backend/api/src/subscriptions/entities/subscription.entity.ts): `backend/api/src/subscriptions/entities/subscription.entity.ts`
- [Credit accounting](https://github.com/datakitpage/datakit/blob/main/backend/api/src/credits/credits.service.ts): `backend/api/src/credits/credits.service.ts`
- [Usage records](https://github.com/datakitpage/datakit/blob/main/backend/api/src/credits/entities/credit-usage.entity.ts): `backend/api/src/credits/entities/credit-usage.entity.ts`
- [Postgres endpoints](https://github.com/datakitpage/datakit/blob/main/backend/api/src/postgres-proxy/postgres-proxy.controller.ts): `backend/api/src/postgres-proxy/postgres-proxy.controller.ts`
- [Postgres proxy](https://github.com/datakitpage/datakit/blob/main/backend/api/src/postgres-proxy/postgres-proxy.service.ts): `backend/api/src/postgres-proxy/postgres-proxy.service.ts`

### Other components

- **Data analyst**
- **Connected PostgreSQL**

## Connections

- Data analyst → Studio shell: uses (evidence: `README.md`)
- Studio shell → Dataset import: starts import (evidence: `README.md`)
- Dataset import → Local data engine: loads locally (evidence: `README.md`)
- Remote connectors → Local data engine: imports data (evidence: `README.md`)
- Studio shell → Grid and inspection: opens preview (evidence: `README.md`)
- Grid and inspection → Quality analysis: analyzes data (evidence: `README.md`)
- Studio shell → SQL workspace: opens SQL (evidence: `README.md`)
- SQL workspace → DuckDB queries: runs SQL (evidence: `README.md`)
- Studio shell → AI assistant: asks questions (evidence: `README.md`)
- Studio shell → Python notebooks: opens notebooks (evidence: `README.md`)
- Data analyst → Auth endpoints: signs in (evidence: `backend/api/src/auth/auth.controller.ts`)
- Auth endpoints → Authentication: handles auth (evidence: `backend/api/src/auth/auth.controller.ts`)
- Authentication → User operations: looks up users (evidence: `backend/api/src/auth/auth.service.ts`)
- Authentication → Plans and billing: creates plan (evidence: `backend/api/src/auth/auth.service.ts`)
- Authentication → Workspace operations: creates workspace (evidence: `backend/api/src/auth/auth.service.ts`)
- Auth endpoints → User accounts: returns profile (evidence: `backend/api/src/auth/auth.controller.ts`)
- Workspace operations → Team membership: manages members
- Plans and billing → Subscription records: persists plans
- Credit accounting → Usage records: records usage (evidence: `backend/api/src/credits/credits.service.ts`)
- Credit accounting → Plans and billing: checks allowance (evidence: `backend/api/src/credits/credits.service.ts`)
- Postgres endpoints → Postgres proxy: routes requests (evidence: `backend/api/src/postgres-proxy/postgres-proxy.controller.ts`)
- Postgres proxy → Connected PostgreSQL: queries database