How nicoryne/trellis works
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: App.tsx Web app · organize.ts AI services · CaptureView.tsx Capture · rag.ts RAG pipeline
Components 25
Browser app
React/Vite SPA for personal capture, graph exploration, chat, and publish review.
- Web app · React/Vite frontend that owns the main user journeys and local-first experience.
apps/web/src/App.tsx - IndexedDB · Browser persistence boundary for private notes and personal graph data.
apps/web/src/lib/idb.ts - Note store · Client-side note and graph state coordination over local storage.
apps/web/src/store/noteStore.ts - Capture · Text, audio, and image intake with organize/review steps.
apps/web/src/views/capture/CaptureView.tsx - Personal graph · Private browser-side graph visualization and navigation.
apps/web/src/views/graph/PersonalGraphView.tsx - Team graph · Governed shared graph view backed by server data.
apps/web/src/views/team/TeamGraphView.tsx - Chat UI · Citation-grounded chat interface with sources and confidence cues.
apps/web/src/views/chat/ChatView.tsx - Publish review · Diff, preservation, and approval flow before sharing content.
apps/web/src/views/publish/RedactionModal.tsx - Graph utils · 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 · Node/Express backend that exposes auth, capture, chat, publish, seed, and graph routes.
apps/api/src/index.ts - Route layer · Thin route group boundary for the backend API surface.
apps/api/src/routes/chat.ts - AI services · Core business logic for organize, classify, embed, chat, and redact workflows.
apps/api/src/services/organize.ts - Prompts · Versioned prompt templates for organization, chat, preservation, and redaction.
apps/api/src/prompts/organize.md - RAG pipeline · Query classification, retrieval, and citation-grounded answer generation.
apps/api/src/services/rag.ts - Redaction pipeline · Two-pass publish boundary with PII tokenization and sanitization.
apps/api/src/services/redaction.ts - Postgres · System of record for team knowledge, embeddings, and publication metadata.
apps/api/src/db/schema.sql - Queries · Typed query layer over the database schema and pool.
apps/api/src/db/queries.ts - Seed data · 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 · Vercel and Railway/Render deployment configuration.
infra/deploy/vercel.json - Local stack · Docker Compose wiring for local supporting services.
infra/docker-compose.yml
Knowledge vault
Non-runtime product and architecture wiki used as living documentation.
- Vault · Obsidian-style documentation and architecture knowledge base; not runtime code.
vault/README.md
External services
Third-party AI, privacy, and data platform dependencies.
- Gemini · Model provider for organization, chat generation, and image understanding.
- Whisper · Audio transcription path for capture.
- Presidio · First-pass tokenization and privacy detection in publishing.
- pgvector · Vector retrieval capability within Postgres.
Connections 28
- 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.