blob: da9208e5649b034a3a17d54ba51ec8d0f8d7e998 (
plain) (
blame)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Repository Structure
This is a **Turbo monorepo** containing multiple applications and shared packages:
### Applications (`apps/`)
- **`web/`** - Next.js web application
- **`mcp/`** - Model Context Protocol server
## Development Commands
### Root Level (Monorepo)
- `bun run dev` - Start all applications in development mode
- `bun run build` - Build all applications
- `bun run check-types` - Run TypeScript checks across all apps
- `bun run format-lint` - Format and lint code using Biome
### Web Application (`apps/web/`)
- `bun run dev` - Start Next.js development server
- `bun run build` - Build Next.js application
- `bun run lint` - Run Next.js linting
## Architecture Overview
### Core Technology Stack
- **Runtime**: Next.js (web)
- **Framework**: Next.js (web)
- **Language**: TypeScript throughout
- **Package Manager**: Bun
- **Monorepo**: Turbo
- **Authentication**: Better Auth
- **Monitoring**: Sentry
### API Application (Primary Backend)
The API serves as the core backend with these key features:
**Key API Routes**
- `/v3/documents` - CRUD operations for documents/memories
- `/v3/search` - Semantic search across indexed content
- `/v3/connections` - External service integrations (Google Drive, Notion, OneDrive)
- `/v3/settings` - Organization and user settings
- `/v3/analytics` - Usage analytics and reporting
- `/api/auth/*` - Authentication endpoints
### Web Application
Next.js application providing user interface for:
## Key Libraries & Dependencies
### Shared Dependencies
- `better-auth` - Authentication system with organization support
- `drizzle-orm` - Database ORM
- `zod` - Schema validation
- `hono` - Web framework (API & MCP)
- `@sentry/*` - Error monitoring
- `turbo` - Monorepo build system
### Web-Specific
- `next` - React framework
- `@radix-ui/*` - UI components
- `@tanstack/react-query` - Data fetching
- `recharts` - Analytics visualization
## Development Workflow
### Content Processing Pipeline
All content goes through the `IngestContentWorkflow` which handles:
- Content type detection and extraction
- AI-powered summarization and automatic tagging
- Vector embedding generation using Cloudflare AI
- Chunking for semantic search optimization
- Space relationship management
### Environment Configuration
- Uses `wrangler.jsonc` for Cloudflare Workers configuration
- Supports staging and production environments
- Requires Cloudflare bindings: Hyperdrive (DB), AI, KV storage, Workflows
- Cron triggers every 4 hours for connection imports
### Error Handling & Monitoring
- HTTPException for consistent API error responses
- Sentry integration with user and organization context
- Custom logging that filters analytics noise
## Code Quality & Standards
### Linting & Formatting
- **Biome** used for linting and formatting across the monorepo
- Run `bun run format-lint` to format and lint all code
- Configuration in `biome.json` at repository root
### TypeScript
- Strict TypeScript configuration with `@total-typescript/tsconfig`
- Type checking with `bun run check-types`
- Cloudflare Workers type generation with `cf-typegen`
### Database Management
- Drizzle ORM with schema located in shared packages
- Database migrations handled through Drizzle Kit
- Schema types automatically generated and shared
## Security & Best Practices
### Authentication
- Better Auth handles user authentication and organization management
- API key authentication for external access
- Role-based access control within organizations
### Data Handling
- Content hashing to prevent duplicate processing
- Secure handling of external service credentials
- Automatic content type detection and validation
### Deployment
- Cloudflare Workers for scalable serverless deployment
- Source map uploads to Sentry for production debugging
- Environment-specific configuration management
|