# haoxuanzheng/pi architecture

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

## Overview

LifeGraph is a private-by-default personal knowledge system: users capture and organize versioned objects, connect and authorize them, then use retrieval and AI assistance or deliberately publish projections. The map follows the API/UI into domain services and PostgreSQL-backed repositories, with separate branches for imports, files, identity, and account operations. Evidence is strongest for the sampled object, Ask, publication, permissions, retrieval, and storage paths; other documented capabilities are included without guessing at unsampled internal call chains.

Main entry points: [`packages/db/src/repositories/objects.ts`](https://github.com/haoxuanzheng/pi/blob/main/packages/db/src/repositories/objects.ts) (Objects and revisions), [`packages/db/src/schema.ts`](https://github.com/haoxuanzheng/pi/blob/main/packages/db/src/schema.ts) (PostgreSQL schema), [`packages/db/src/repositories/retrieval.ts`](https://github.com/haoxuanzheng/pi/blob/main/packages/db/src/repositories/retrieval.ts) (Hybrid retrieval), [`apps/web/app`](https://github.com/haoxuanzheng/pi/tree/main/apps/web/app) (Web application)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experience["Web experience"]
  node_web["Web application"]
  node_object_api["Object API<br/>[route.ts]"]
  node_editor["Library editor<br/>[ObjectEditor.tsx]"]
  node_ask_api["Ask API<br/>[route.ts]"]
  node_publish_api["Publication API<br/>[route.ts]"]
end

subgraph group_core["Knowledge core"]
  node_object_repo["Objects and revisions<br/>[objects.ts]"]
  node_permission_repo["Permission engine<br/>[permissions.ts]"]
  node_permission_rules["Capability decisions<br/>[index.ts]"]
  node_graph_repo["Object relationships<br/>[relationships.ts]"]
  node_publication_repo["Public projections<br/>[publications.ts]"]
  node_database[("PostgreSQL schema<br/>[schema.ts]")]
end

subgraph group_ai["AI and retrieval"]
  node_ask_service["Evidence-grounded answers<br/>[index.ts]"]
  node_ai_service["AI proposals<br/>[index.ts]"]
  node_retrieval_repo["Hybrid retrieval<br/>[retrieval.ts]"]
  node_retrieval_logic["Chunking and budgets<br/>[index.ts]"]
end

subgraph group_capture["Capture and integrations"]
  node_import_api["Import API<br/>[route.ts]"]
  node_importers["Provider importers<br/>[google-drive.ts]"]
  node_entity_resolution["Person resolution<br/>[index.ts]"]
  node_file_api["File API<br/>[route.ts]"]
  node_storage["File storage adapters<br/>[index.ts]"]
end

subgraph group_account["Identity and account"]
  node_auth["Authentication<br/>[index.ts]"]
  node_connections["Provider connections<br/>[index.ts]"]
  node_privacy["Account export and deletion<br/>[index.ts]"]
  node_analytics["Onboarding and analytics<br/>[index.ts]"]
end

node_user(("User"))

node_user -->|"uses"| node_web
node_web -->|"creates objects"| node_object_api
node_object_api -->|"creates and lists"| node_object_repo
node_editor -->|"edits revisions"| node_object_repo
node_object_repo -->|"checks access"| node_permission_repo
node_permission_repo -->|"decides capabilities"| node_permission_rules
node_object_repo -->|"persists snapshots"| node_database
node_permission_repo -->|"reads and writes grants"| node_database
node_graph_repo -->|"authorizes endpoints"| node_permission_repo
node_graph_repo -->|"stores relationships"| node_database
node_user -->|"asks questions"| node_ask_api
node_ask_api -->|"classifies and answers"| node_ask_service
node_ask_api -->|"searches evidence"| node_retrieval_repo
node_ask_api -->|"loads result metadata"| node_object_repo
node_ask_service -->|"uses AI provider"| node_ai_service
node_ask_service -->|"uses retrieval types"| node_retrieval_logic
node_retrieval_repo -->|"chunks and budgets"| node_retrieval_logic
node_retrieval_repo -->|"loads objects"| node_object_repo
node_retrieval_repo -->|"checks indexing access"| node_permission_repo
node_retrieval_repo -->|"stores embeddings"| node_database
node_user -->|"publishes selected views"| node_publish_api
node_publish_api -->|"creates projections"| node_publication_repo
node_publication_repo -->|"stores projections"| node_database
node_web -->|"starts imports"| node_import_api
node_import_api -->|"dispatches provider import"| node_importers
node_importers -->|"creates private objects"| node_object_repo
node_importers -.->|"resolves people"| node_entity_resolution
node_web -->|"uploads attachments"| node_file_api
node_file_api -.->|"requests file storage"| node_storage
node_storage -.->|"records file metadata"| node_database
node_user -->|"signs in"| node_auth
node_auth -->|"provides authenticated access"| node_web
node_user -->|"connects providers"| node_connections
node_user -->|"exports or deletes account"| node_privacy
node_user -->|"completes onboarding"| node_analytics

click node_web "https://github.com/haoxuanzheng/pi/tree/main/apps/web/app"
click node_object_api "https://github.com/haoxuanzheng/pi/blob/main/apps/web/app/api/v1/objects/route.ts"
click node_editor "https://github.com/haoxuanzheng/pi/blob/main/apps/web/app/library/%5BobjectId%5D/ObjectEditor.tsx"
click node_ask_api "https://github.com/haoxuanzheng/pi/blob/main/apps/web/app/api/v1/ask/route.ts"
click node_publish_api "https://github.com/haoxuanzheng/pi/blob/main/apps/web/app/api/v1/publications/route.ts"
click node_object_repo "https://github.com/haoxuanzheng/pi/blob/main/packages/db/src/repositories/objects.ts"
click node_permission_repo "https://github.com/haoxuanzheng/pi/blob/main/packages/db/src/repositories/permissions.ts"
click node_permission_rules "https://github.com/haoxuanzheng/pi/blob/main/packages/permissions/src/index.ts"
click node_graph_repo "https://github.com/haoxuanzheng/pi/blob/main/packages/db/src/repositories/relationships.ts"
click node_publication_repo "https://github.com/haoxuanzheng/pi/blob/main/packages/db/src/repositories/publications.ts"
click node_database "https://github.com/haoxuanzheng/pi/blob/main/packages/db/src/schema.ts"
click node_ask_service "https://github.com/haoxuanzheng/pi/blob/main/packages/ask/src/index.ts"
click node_ai_service "https://github.com/haoxuanzheng/pi/blob/main/packages/ai/src/index.ts"
click node_retrieval_repo "https://github.com/haoxuanzheng/pi/blob/main/packages/db/src/repositories/retrieval.ts"
click node_retrieval_logic "https://github.com/haoxuanzheng/pi/blob/main/packages/retrieval/src/index.ts"
click node_import_api "https://github.com/haoxuanzheng/pi/blob/main/apps/web/app/api/v1/imports/start/route.ts"
click node_importers "https://github.com/haoxuanzheng/pi/blob/main/packages/imports/src/google-drive.ts"
click node_entity_resolution "https://github.com/haoxuanzheng/pi/blob/main/packages/entities/src/index.ts"
click node_file_api "https://github.com/haoxuanzheng/pi/blob/main/apps/web/app/api/v1/files/upload-intent/route.ts"
click node_storage "https://github.com/haoxuanzheng/pi/blob/main/packages/storage/src/index.ts"
click node_auth "https://github.com/haoxuanzheng/pi/blob/main/packages/auth/src/index.ts"
click node_connections "https://github.com/haoxuanzheng/pi/blob/main/packages/connections/src/index.ts"
click node_privacy "https://github.com/haoxuanzheng/pi/blob/main/packages/privacy/src/index.ts"
click node_analytics "https://github.com/haoxuanzheng/pi/blob/main/packages/analytics/src/index.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_object_api,node_editor,node_ask_api,node_publish_api,node_user toneBlue
class node_object_repo,node_permission_repo,node_permission_rules,node_graph_repo,node_publication_repo,node_database toneAmber
class node_ask_service,node_ai_service,node_retrieval_repo,node_retrieval_logic toneMint
class node_import_api,node_importers,node_entity_resolution,node_file_api,node_storage toneRose
class node_auth,node_connections,node_privacy,node_analytics toneIndigo
```

## Components

### Web experience

- [Web application](https://github.com/haoxuanzheng/pi/tree/main/apps/web/app): `apps/web/app`
- [Object API](https://github.com/haoxuanzheng/pi/blob/main/apps/web/app/api/v1/objects/route.ts): `apps/web/app/api/v1/objects/route.ts`
- [Library editor](https://github.com/haoxuanzheng/pi/blob/main/apps/web/app/library/%5BobjectId%5D/ObjectEditor.tsx): `apps/web/app/library/[objectId]/ObjectEditor.tsx`
- [Ask API](https://github.com/haoxuanzheng/pi/blob/main/apps/web/app/api/v1/ask/route.ts): `apps/web/app/api/v1/ask/route.ts`
- [Publication API](https://github.com/haoxuanzheng/pi/blob/main/apps/web/app/api/v1/publications/route.ts): `apps/web/app/api/v1/publications/route.ts`

### Knowledge core

- [Objects and revisions](https://github.com/haoxuanzheng/pi/blob/main/packages/db/src/repositories/objects.ts): `packages/db/src/repositories/objects.ts`
- [Permission engine](https://github.com/haoxuanzheng/pi/blob/main/packages/db/src/repositories/permissions.ts): `packages/db/src/repositories/permissions.ts`
- [Capability decisions](https://github.com/haoxuanzheng/pi/blob/main/packages/permissions/src/index.ts): `packages/permissions/src/index.ts`
- [Object relationships](https://github.com/haoxuanzheng/pi/blob/main/packages/db/src/repositories/relationships.ts): `packages/db/src/repositories/relationships.ts`
- [Public projections](https://github.com/haoxuanzheng/pi/blob/main/packages/db/src/repositories/publications.ts): `packages/db/src/repositories/publications.ts`
- [PostgreSQL schema](https://github.com/haoxuanzheng/pi/blob/main/packages/db/src/schema.ts): `packages/db/src/schema.ts`

### AI and retrieval

- [Evidence-grounded answers](https://github.com/haoxuanzheng/pi/blob/main/packages/ask/src/index.ts): `packages/ask/src/index.ts`
- [AI proposals](https://github.com/haoxuanzheng/pi/blob/main/packages/ai/src/index.ts): `packages/ai/src/index.ts`
- [Hybrid retrieval](https://github.com/haoxuanzheng/pi/blob/main/packages/db/src/repositories/retrieval.ts): `packages/db/src/repositories/retrieval.ts`
- [Chunking and budgets](https://github.com/haoxuanzheng/pi/blob/main/packages/retrieval/src/index.ts): `packages/retrieval/src/index.ts`

### Capture and integrations

- [Import API](https://github.com/haoxuanzheng/pi/blob/main/apps/web/app/api/v1/imports/start/route.ts): `apps/web/app/api/v1/imports/start/route.ts`
- [Provider importers](https://github.com/haoxuanzheng/pi/blob/main/packages/imports/src/google-drive.ts): `packages/imports/src/google-drive.ts`
- [Person resolution](https://github.com/haoxuanzheng/pi/blob/main/packages/entities/src/index.ts): `packages/entities/src/index.ts`
- [File API](https://github.com/haoxuanzheng/pi/blob/main/apps/web/app/api/v1/files/upload-intent/route.ts): `apps/web/app/api/v1/files/upload-intent/route.ts`
- [File storage adapters](https://github.com/haoxuanzheng/pi/blob/main/packages/storage/src/index.ts): `packages/storage/src/index.ts`

### Identity and account

- [Authentication](https://github.com/haoxuanzheng/pi/blob/main/packages/auth/src/index.ts): `packages/auth/src/index.ts`
- [Provider connections](https://github.com/haoxuanzheng/pi/blob/main/packages/connections/src/index.ts): `packages/connections/src/index.ts`
- [Account export and deletion](https://github.com/haoxuanzheng/pi/blob/main/packages/privacy/src/index.ts): `packages/privacy/src/index.ts`
- [Onboarding and analytics](https://github.com/haoxuanzheng/pi/blob/main/packages/analytics/src/index.ts): `packages/analytics/src/index.ts`

### Other components

- **User**

## Connections

- User → Web application: uses
- Web application → Object API: creates objects (evidence: `apps/web/app/api/v1/objects/route.ts`)
- Object API → Objects and revisions: creates and lists (evidence: `apps/web/app/api/v1/objects/route.ts`)
- Library editor → Objects and revisions: edits revisions
- Objects and revisions → Permission engine: checks access (evidence: `packages/db/src/repositories/objects.ts`)
- Permission engine → Capability decisions: decides capabilities (evidence: `packages/db/src/repositories/permissions.ts`)
- Objects and revisions → PostgreSQL schema: persists snapshots (evidence: `packages/db/src/repositories/objects.ts`)
- Permission engine → PostgreSQL schema: reads and writes grants (evidence: `packages/db/src/repositories/permissions.ts`)
- Object relationships → Permission engine: authorizes endpoints
- Object relationships → PostgreSQL schema: stores relationships (evidence: `packages/db/src/schema.ts`)
- User → Ask API: asks questions
- Ask API → Evidence-grounded answers: classifies and answers (evidence: `apps/web/app/api/v1/ask/route.ts`)
- Ask API → Hybrid retrieval: searches evidence (evidence: `apps/web/app/api/v1/ask/route.ts`)
- Ask API → Objects and revisions: loads result metadata (evidence: `apps/web/app/api/v1/ask/route.ts`)
- Evidence-grounded answers → AI proposals: uses AI provider (evidence: `packages/ask/src/index.ts`)
- Evidence-grounded answers → Chunking and budgets: uses retrieval types (evidence: `packages/ask/src/index.ts`)
- Hybrid retrieval → Chunking and budgets: chunks and budgets (evidence: `packages/db/src/repositories/retrieval.ts`)
- Hybrid retrieval → Objects and revisions: loads objects (evidence: `packages/db/src/repositories/retrieval.ts`)
- Hybrid retrieval → Permission engine: checks indexing access (evidence: `packages/db/src/repositories/retrieval.ts`)
- Hybrid retrieval → PostgreSQL schema: stores embeddings (evidence: `packages/db/src/repositories/retrieval.ts`)
- User → Publication API: publishes selected views
- Publication API → Public projections: creates projections (evidence: `apps/web/app/api/v1/publications/route.ts`)
- Public projections → PostgreSQL schema: stores projections (evidence: `packages/db/src/schema.ts`)
- Web application → Import API: starts imports
- Import API → Provider importers: dispatches provider import (evidence: `apps/web/app/api/v1/imports/start/route.ts`)
- Provider importers → Objects and revisions: creates private objects
- Provider importers → Person resolution: resolves people
- Web application → File API: uploads attachments
- File API → File storage adapters: requests file storage
- File storage adapters → PostgreSQL schema: records file metadata
- User → Authentication: signs in
- Authentication → Web application: provides authenticated access (evidence: `apps/web/app/auth/confirm/route.ts`)
- User → Provider connections: connects providers
- User → Account export and deletion: exports or deletes account
- User → Onboarding and analytics: completes onboarding