# nicoryne/trellis architecture

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

- Interactive diagram: https://gitdiagram.com/nicoryne/trellis
- Repository: https://github.com/nicoryne/trellis

## Overview

1. **Overall shape**
   Trellis is a two-layer knowledge platform: a **private personal graph** in the browser and a **governed team graph** in the backend. The product flow is: capture locally, organize with AI, optionally publish after redaction, then retrieve via citation-grounded chat over the team graph.

2. **Frontend boundary: React/Vite SPA**
   `apps/web` is a single-page app built with React 18, Vite, and TypeScript. It owns the user experience for login, capture, chat, personal graph, team graph, and publish review. The app is organized by feature views rather than by technical layer, which matches the main user journeys.

3. **Local-first personal layer**
   The browser stores personal notes and graph data in **IndexedDB** through `apps/web/src/lib/idb.ts` and `store/noteStore.ts`. This is the private workspace where captured text/audio/image inputs live before any publication decision. That local storage boundary is important: personal data is not treated as immediately server-owned.

4. **Capture pipeline**
   The capture UI supports **text, audio, and image** intake. Audio uses a Whisper-backed transcription path; image capture uses Gemini Vision/OCR-style processing. After intake, the frontend sends the note through organization and enrichment flows so it can be classified and linked into the personal graph.

5. **AI organization and enrichment**
   The backend service layer in `apps/api/src/services` orchestrates Gemini-driven extraction and categorization. Key responsibilities include entity extraction, note organization, classification, embedding generation, conversational response generation, and redaction. Prompt templates are versioned separately under `apps/api/src/prompts`, which makes the AI behavior a distinct subsystem.

6. **Governed publishing pipeline**
   Publishing is a separate path from capture. The app presents a diff/review experience, then the backend applies a **two-pass redaction pipeline**: first PII tokenization via **Microsoft Presidio**, then generalization/sanitization via Gemini. This creates a controlled boundary between private capture and shared team knowledge.

7. **Backend API boundary**
   `apps/api` is a Node.js 20 + Express service exposing route groups for auth, capture, chat, publish, seed, health, and team graph access. Middleware handles authentication and rate limiting. The route layer is thin; the core business logic lives in services, which keeps API shape separate from AI/data orchestration.

8. **Data layer**
   The backend persists shared knowledge in **PostgreSQL 16** with **pgvector** for retrieval. `src/db/schema.sql`, `queries.ts`, and `pool.ts` define the schema and query boundary. This database is the system of record for the governed team graph, embeddings, and publication metadata.

9. **Retrieval and chat**
   The chat experience is powered by a RAG pipeline in `apps/api/src/services/rag.ts` and conversation orchestration in `conversational.ts`. Queries are classified, relevant nodes are retrieved from Postgres/pgvector, and answers are generated with citations back to source nodes. The frontend chat view then pairs the text answer with source chips, confidence cues, and graph-overlay UI.

10. **Graph visualization subsystem**
   Graph rendering is a major presentation layer in the web app, with separate personal and team graph views plus zoom controls and node preview components. The frontend includes graph utilities, physics, and diff helpers to manage layout and transitions. This is the visual counterpart to the knowledge graph model stored in the backend and local IndexedDB.

11. **Auth and access control**
   Authentication is handled in both the frontend client and backend route/middleware layer. The architecture suggests that authenticated users can work in their personal space, while published/shared content is gated by server-side authorization before it enters the team graph or becomes queryable.

12. **Seed and demo data**
   The repo includes dedicated seed scripts for team graph content and personal graph samples. This matters architecturally because the product is demo-driven: the capture → publish → retrieve loop needs representative graph content and edge derivation logic to show the intended experience.

13. **Deployment and local infrastructure**
   The frontend is intended for **Vercel**, while the backend and Postgres are deployed on **Railway/Render**. Local development uses Docker Compose to stand up supporting services, including **Postgres** and **Presidio**. That means the runtime is split between a browser-hosted SPA and a server-hosted API + database stack.

14. **Non-runtime knowledge base**
   The `vault/` directory is not application runtime code; it is an Obsidian-style product and architecture wiki used to capture concepts, decisions, entities, and design history. It functions as the project’s living documentation and source-of-truth for product rationale, not as a deployed subsystem.

15. **What to diagram**
   A good architecture diagram should show: browser SPA and local IndexedDB on the left; Express API in the middle with auth, capture, publish, chat, and team graph routes; AI services and prompt-driven orchestration beside it; PostgreSQL + pgvector as the governed knowledge store; and external AI/privacy services like Gemini, Whisper, and Presidio feeding the capture, redaction, and retrieval pipelines.

Main entry points: [`apps/web/src/App.tsx`](https://github.com/nicoryne/trellis/blob/main/apps/web/src/App.tsx) (Web app), [`apps/api/src/services/organize.ts`](https://github.com/nicoryne/trellis/blob/main/apps/api/src/services/organize.ts) (AI services), [`apps/web/src/views/capture/CaptureView.tsx`](https://github.com/nicoryne/trellis/blob/main/apps/web/src/views/capture/CaptureView.tsx) (Capture), [`apps/api/src/services/rag.ts`](https://github.com/nicoryne/trellis/blob/main/apps/api/src/services/rag.ts) (RAG pipeline)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Browser app"]
  node_web_app["Web app<br/>SPA shell<br/>[App.tsx]"]
  node_web_idb[("IndexedDB<br/>local store<br/>[idb.ts]")]
  node_web_note_store["Note store<br/>client state<br/>[noteStore.ts]"]
  node_web_capture["Capture<br/>input flow<br/>[CaptureView.tsx]"]
  node_web_personal_graph["Personal graph<br/>local view"]
  node_web_team_graph["Team graph<br/>shared view<br/>[TeamGraphView.tsx]"]
  node_web_chat["Chat UI<br/>retrieval view<br/>[ChatView.tsx]"]
  node_web_publish["Publish review<br/>redaction UI<br/>[RedactionModal.tsx]"]
  node_web_graph_utils["Graph utils<br/>viz logic<br/>[graphUtils.ts]"]
end

subgraph group_api["Backend API"]
  node_api_server["API server<br/>Express app<br/>[index.ts]"]
  node_api_routes["Route layer<br/>HTTP boundary<br/>[chat.ts]"]
  node_api_services["AI services<br/>orchestration<br/>[organize.ts]"]
  node_api_prompts["Prompts<br/>template set<br/>[organize.md]"]
  node_api_rag["RAG pipeline<br/>retrieval flow<br/>[rag.ts]"]
  node_api_redaction["Redaction pipeline<br/>privacy flow<br/>[redaction.ts]"]
  node_api_db[("Postgres<br/>shared store<br/>[schema.sql]")]
  node_api_queries["Queries<br/>db boundary<br/>[queries.ts]"]
  node_api_seed["Seed data<br/>demo content<br/>[seed.ts]"]
end

subgraph group_infra["Infrastructure"]
  node_infra_deploy["Deploy config<br/>deployment<br/>[vercel.json]"]
  node_infra_compose["Local stack<br/>dev infra<br/>[docker-compose.yml]"]
end

subgraph group_vault["Knowledge vault"]
  node_vault_docs["Vault<br/>wiki<br/>[README.md]"]
end

subgraph group_external["External services"]
  node_ext_gemini["Gemini<br/>LLM/OCR"]
  node_ext_whisper["Whisper<br/>speech-to-text"]
  node_ext_presidio["Presidio<br/>PII detector"]
  node_ext_pgvector["pgvector<br/>vector search"]
end

node_web_app -->|"renders"| node_web_capture
node_web_app -->|"renders"| node_web_personal_graph
node_web_app -->|"renders"| node_web_team_graph
node_web_app -->|"renders"| node_web_chat
node_web_app -->|"renders"| node_web_publish
node_web_capture -->|"stores"| node_web_note_store
node_web_note_store -->|"persists"| node_web_idb
node_web_graph_utils -.->|"supports"| node_web_personal_graph
node_web_graph_utils -.->|"supports"| node_web_team_graph
node_web_app -->|"calls"| node_api_server
node_api_server -->|"hosts"| node_api_routes
node_api_routes -->|"delegates"| node_api_services
node_api_services -->|"loads"| node_api_prompts
node_api_services -->|"orchestrates"| node_api_rag
node_api_services -->|"orchestrates"| node_api_redaction
node_api_services -->|"queries"| node_api_queries
node_api_queries -->|"persists"| node_api_db
node_api_rag -->|"retrieves"| node_api_db
node_api_rag -->|"uses"| node_ext_pgvector
node_api_redaction -->|"uses"| node_ext_presidio
node_api_services -->|"uses"| node_ext_gemini
node_web_capture -->|"uses"| node_ext_whisper
node_api_seed -->|"seeds"| node_api_db
node_infra_compose -.->|"runs"| node_ext_presidio
node_infra_deploy -.->|"deploys"| node_api_server
node_infra_deploy -.->|"deploys"| node_web_app
node_vault_docs -.->|"documents"| node_api_services
node_vault_docs -.->|"documents"| node_web_capture

click node_web_app "https://github.com/nicoryne/trellis/blob/main/apps/web/src/App.tsx"
click node_web_idb "https://github.com/nicoryne/trellis/blob/main/apps/web/src/lib/idb.ts"
click node_web_note_store "https://github.com/nicoryne/trellis/blob/main/apps/web/src/store/noteStore.ts"
click node_web_capture "https://github.com/nicoryne/trellis/blob/main/apps/web/src/views/capture/CaptureView.tsx"
click node_web_personal_graph "https://github.com/nicoryne/trellis/blob/main/apps/web/src/views/graph/PersonalGraphView.tsx"
click node_web_team_graph "https://github.com/nicoryne/trellis/blob/main/apps/web/src/views/team/TeamGraphView.tsx"
click node_web_chat "https://github.com/nicoryne/trellis/blob/main/apps/web/src/views/chat/ChatView.tsx"
click node_web_publish "https://github.com/nicoryne/trellis/blob/main/apps/web/src/views/publish/RedactionModal.tsx"
click node_web_graph_utils "https://github.com/nicoryne/trellis/blob/main/apps/web/src/lib/graphUtils.ts"
click node_api_server "https://github.com/nicoryne/trellis/blob/main/apps/api/src/index.ts"
click node_api_routes "https://github.com/nicoryne/trellis/blob/main/apps/api/src/routes/chat.ts"
click node_api_services "https://github.com/nicoryne/trellis/blob/main/apps/api/src/services/organize.ts"
click node_api_prompts "https://github.com/nicoryne/trellis/blob/main/apps/api/src/prompts/organize.md"
click node_api_rag "https://github.com/nicoryne/trellis/blob/main/apps/api/src/services/rag.ts"
click node_api_redaction "https://github.com/nicoryne/trellis/blob/main/apps/api/src/services/redaction.ts"
click node_api_db "https://github.com/nicoryne/trellis/blob/main/apps/api/src/db/schema.sql"
click node_api_queries "https://github.com/nicoryne/trellis/blob/main/apps/api/src/db/queries.ts"
click node_api_seed "https://github.com/nicoryne/trellis/blob/main/apps/api/src/seed/seed.ts"
click node_infra_deploy "https://github.com/nicoryne/trellis/blob/main/infra/deploy/vercel.json"
click node_infra_compose "https://github.com/nicoryne/trellis/blob/main/infra/docker-compose.yml"
click node_vault_docs "https://github.com/nicoryne/trellis/blob/main/vault/README.md"

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_app,node_web_idb,node_web_note_store,node_web_capture,node_web_personal_graph,node_web_team_graph,node_web_chat,node_web_publish,node_web_graph_utils toneBlue
class node_api_server,node_api_routes,node_api_services,node_api_prompts,node_api_rag,node_api_redaction,node_api_db,node_api_queries,node_api_seed toneAmber
class node_infra_deploy,node_infra_compose toneMint
class node_vault_docs toneRose
class node_ext_gemini,node_ext_whisper,node_ext_presidio,node_ext_pgvector toneIndigo
```

## Components

### Browser app

React/Vite SPA for personal capture, graph exploration, chat, and publish review.

- [Web app](https://github.com/nicoryne/trellis/blob/main/apps/web/src/App.tsx): SPA shell · React/Vite frontend that owns the main user journeys and local-first experience. · `apps/web/src/App.tsx`
- [IndexedDB](https://github.com/nicoryne/trellis/blob/main/apps/web/src/lib/idb.ts): local store · Browser persistence boundary for private notes and personal graph data. · `apps/web/src/lib/idb.ts`
- [Note store](https://github.com/nicoryne/trellis/blob/main/apps/web/src/store/noteStore.ts): client state · Client-side note and graph state coordination over local storage. · `apps/web/src/store/noteStore.ts`
- [Capture](https://github.com/nicoryne/trellis/blob/main/apps/web/src/views/capture/CaptureView.tsx): input flow · Text, audio, and image intake with organize/review steps. · `apps/web/src/views/capture/CaptureView.tsx`
- [Personal graph](https://github.com/nicoryne/trellis/blob/main/apps/web/src/views/graph/PersonalGraphView.tsx): local view · Private browser-side graph visualization and navigation. · `apps/web/src/views/graph/PersonalGraphView.tsx`
- [Team graph](https://github.com/nicoryne/trellis/blob/main/apps/web/src/views/team/TeamGraphView.tsx): shared view · Governed shared graph view backed by server data. · `apps/web/src/views/team/TeamGraphView.tsx`
- [Chat UI](https://github.com/nicoryne/trellis/blob/main/apps/web/src/views/chat/ChatView.tsx): retrieval view · Citation-grounded chat interface with sources and confidence cues. · `apps/web/src/views/chat/ChatView.tsx`
- [Publish review](https://github.com/nicoryne/trellis/blob/main/apps/web/src/views/publish/RedactionModal.tsx): redaction UI · Diff, preservation, and approval flow before sharing content. · `apps/web/src/views/publish/RedactionModal.tsx`
- [Graph utils](https://github.com/nicoryne/trellis/blob/main/apps/web/src/lib/graphUtils.ts): viz logic · Graph layout, diffing, physics, and interaction helpers. · `apps/web/src/lib/graphUtils.ts`

### Backend API

Express service for auth, capture, publish, retrieval, and team graph access.

- [API server](https://github.com/nicoryne/trellis/blob/main/apps/api/src/index.ts): Express app · Node/Express backend that exposes auth, capture, chat, publish, seed, and graph routes. · `apps/api/src/index.ts`
- [Route layer](https://github.com/nicoryne/trellis/blob/main/apps/api/src/routes/chat.ts): HTTP boundary · Thin route group boundary for the backend API surface. · `apps/api/src/routes/chat.ts`
- [AI services](https://github.com/nicoryne/trellis/blob/main/apps/api/src/services/organize.ts): orchestration · Core business logic for organize, classify, embed, chat, and redact workflows. · `apps/api/src/services/organize.ts`
- [Prompts](https://github.com/nicoryne/trellis/blob/main/apps/api/src/prompts/organize.md): template set · Versioned prompt templates for organization, chat, preservation, and redaction. · `apps/api/src/prompts/organize.md`
- [RAG pipeline](https://github.com/nicoryne/trellis/blob/main/apps/api/src/services/rag.ts): retrieval flow · Query classification, retrieval, and citation-grounded answer generation. · `apps/api/src/services/rag.ts`
- [Redaction pipeline](https://github.com/nicoryne/trellis/blob/main/apps/api/src/services/redaction.ts): privacy flow · Two-pass publish boundary with PII tokenization and sanitization. · `apps/api/src/services/redaction.ts`
- [Postgres](https://github.com/nicoryne/trellis/blob/main/apps/api/src/db/schema.sql): shared store · System of record for team knowledge, embeddings, and publication metadata. · `apps/api/src/db/schema.sql`
- [Queries](https://github.com/nicoryne/trellis/blob/main/apps/api/src/db/queries.ts): db boundary · Typed query layer over the database schema and pool. · `apps/api/src/db/queries.ts`
- [Seed data](https://github.com/nicoryne/trellis/blob/main/apps/api/src/seed/seed.ts): demo content · Demo and onboarding content plus derived edge generation. · `apps/api/src/seed/seed.ts`

### Infrastructure

Deployment and local runtime wiring for app and supporting services.

- [Deploy config](https://github.com/nicoryne/trellis/blob/main/infra/deploy/vercel.json): deployment · Vercel and Railway/Render deployment configuration. · `infra/deploy/vercel.json`
- [Local stack](https://github.com/nicoryne/trellis/blob/main/infra/docker-compose.yml): dev infra · Docker Compose wiring for local supporting services. · `infra/docker-compose.yml`

### Knowledge vault

Non-runtime product and architecture wiki used as living documentation.

- [Vault](https://github.com/nicoryne/trellis/blob/main/vault/README.md): wiki · Obsidian-style documentation and architecture knowledge base; not runtime code. · `vault/README.md`

### External services

Third-party AI, privacy, and data platform dependencies.

- **Gemini**: LLM/OCR · Model provider for organization, chat generation, and image understanding.
- **Whisper**: speech-to-text · Audio transcription path for capture.
- **Presidio**: PII detector · First-pass tokenization and privacy detection in publishing.
- **pgvector**: vector search · Vector retrieval capability within Postgres.

## Connections

- Web app → Capture: renders · Main SPA renders the capture journey.
- Web app → Personal graph: renders · Main SPA renders personal graph exploration.
- Web app → Team graph: renders · Main SPA renders team graph exploration.
- Web app → Chat UI: renders · Main SPA renders chat and citation UI.
- Web app → Publish review: renders · Main SPA renders publish review and redaction UI.
- Capture → Note store: stores · Captured content is staged in client state.
- Note store → IndexedDB: persists · Personal notes are persisted locally in IndexedDB.
- Graph utils → Personal graph: supports · Visualization helpers power the graph view.
- Graph utils → Team graph: supports · Visualization helpers power the shared graph view.
- Web app → API server: calls · Frontend uses the backend API for authenticated workflows.
- API server → Route layer: hosts · Express server exposes route groups.
- Route layer → AI services: delegates · Routes forward to service-layer orchestration.
- AI services → Prompts: loads · Services use versioned prompt templates.
- AI services → RAG pipeline: orchestrates · Chat and retrieval flow is handled in RAG services.
- AI services → Redaction pipeline: orchestrates · Publish path invokes the redaction pipeline.
- AI services → Queries: queries · Services read and write through the query boundary.
- Queries → Postgres: persists · Query layer talks to Postgres as system of record.
- RAG pipeline → Postgres: retrieves · RAG searches shared knowledge in Postgres.
- RAG pipeline → pgvector: uses · Vector similarity retrieval relies on pgvector.
- Redaction pipeline → Presidio: uses · First pass redaction uses PII detection/tokenization.
- AI services → Gemini: uses · Organization, chat, and sanitization depend on Gemini.
- Capture → Whisper: uses · Audio capture path transcribes through Whisper.
- Seed data → Postgres: seeds · Seed scripts populate the governed knowledge store.
- Local stack → Presidio: runs · Local compose brings up privacy services for development.
- Deploy config → API server: deploys · Deployment config targets the backend runtime.
- Deploy config → Web app: deploys · Deployment config targets the frontend runtime.
- Vault → AI services: documents · Vault captures architecture and service rationale.
- Vault → Capture: documents · Vault captures product and implementation rationale.
