@hiai-gg/hiai-docs 0.0.1

package/docker-compose.yml

@@ -0,0 +1,218 @@
+# hiai-docs Docker Compose
+# Copy .env.example to .env before running
+
+services:
+  postgres:
+    image: pgvector/pgvector:pg18
+    restart: unless-stopped
+    ports:
+      - "${DB_PORT:-5433}:5432"
+    volumes:
+      - pgdata:/var/lib/postgresql
+      - ./init.sql:/docker-entrypoint-initdb.d/init.sql:ro
+    environment:
+      POSTGRES_DB: ${DB_NAME:-hiai_docs}
+      POSTGRES_USER: ${DB_USER:-aiuser}
+      POSTGRES_PASSWORD: ${DB_PASSWORD:-changeme}
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${DB_USER:-aiuser} -d ${DB_NAME:-hiai_docs}"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - hiai-docs-net
+    deploy:
+      resources:
+        limits:
+          memory: 2G
+          cpus: "2"
+
+  redis:
+    image: redis:8-alpine
+    restart: unless-stopped
+    ports:
+      - "${REDIS_PORT:-6384}:6379"
+    volumes:
+      - redis_data:/data
+    healthcheck:
+      test: ["CMD", "redis-cli", "ping"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - hiai-docs-net
+    deploy:
+      resources:
+        limits:
+          memory: 256M
+          cpus: "0.5"
+
+  ollama:
+    image: ollama/ollama:0.13.4
+    restart: unless-stopped
+    # 11435 host: avoids conflict with primary Ollama on 11434
+    ports:
+      - "11435:11434"
+    volumes:
+      - ollama_data:/root/.ollama
+    healthcheck:
+      test: ["CMD", "ollama", "list"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 30s
+    networks:
+      - hiai-docs-net
+    deploy:
+      resources:
+        limits:
+          memory: 2G
+          cpus: "2"
+
+  minio:
+    image: minio/minio:RELEASE.2025-06-13T14-19-31Z
+    restart: unless-stopped
+    # 9021 host: avoids conflict with webs-minio (9001) and ai-shared-minio (9011)
+    ports:
+      - "9000:9000"
+      - "9021:9001"
+    volumes:
+      - minio_data:/data
+    command: server /data --console-address ":9001"
+    environment:
+      MINIO_ROOT_USER: ${MINIO_ACCESS_KEY:-minioadmin}
+      MINIO_ROOT_PASSWORD: ${MINIO_SECRET_KEY:-minioadmin}
+    healthcheck:
+      test: ["CMD", "mc", "ready", "local"]
+      interval: 10s
+      timeout: 5s
+      retries: 5
+    networks:
+      - hiai-docs-net
+    deploy:
+      resources:
+        limits:
+          memory: 256M
+          cpus: "0.5"
+
+  api:
+    build:
+      context: .
+      dockerfile: Dockerfile.backend
+      network: host
+    restart: unless-stopped
+    ports:
+      - "${API_PORT:-50700}:50700"
+    depends_on:
+      postgres:
+        condition: service_healthy
+      redis:
+        condition: service_healthy
+      minio:
+        condition: service_healthy
+      ollama:
+        condition: service_healthy
+    healthcheck:
+      # $$ escapes compose interpolation so API_PORT is resolved at runtime
+      # inside the container (not baked in at compose-parse time).
+      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:$${API_PORT}/api/health || exit 1"]
+      interval: 15s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+    environment:
+      DATABASE_URL: postgresql://${DB_USER:-aiuser}:${DB_PASSWORD:-changeme}@postgres:5432/${DB_NAME:-hiai_docs}
+      REDIS_URL: redis://redis:6379
+      MINIO_ENDPOINT: minio
+      MINIO_PORT: 9000
+      MINIO_ACCESS_KEY: ${MINIO_ACCESS_KEY:-minioadmin}
+      MINIO_SECRET_KEY: ${MINIO_SECRET_KEY:-minioadmin}
+      MINIO_BUCKET: ${MINIO_BUCKET:-hiai-docs}
+      MINIO_PUBLIC_ENDPOINT: localhost
+      MINIO_PUBLIC_PORT: 9000
+      BETTER_AUTH_SECRET: ${BETTER_AUTH_SECRET}
+      BETTER_AUTH_URL: ${BETTER_AUTH_URL:-http://localhost:50700}
+      CORS_ORIGINS: ${CORS_ORIGINS:-http://localhost:50701,http://127.0.0.1:50701}
+      EMBEDDING_PROVIDER: ${EMBEDDING_PROVIDER:-ollama}
+      EMBEDDING_MODEL: ${EMBEDDING_MODEL:-nomic-embed-text}
+      EMBEDDING_OLLAMA_URL: http://ollama:11434
+      EMBEDDING_FALLBACK_PROVIDER: ${EMBEDDING_FALLBACK_PROVIDER:-openrouter}
+      EMBEDDING_FALLBACK_MODEL: ${EMBEDDING_FALLBACK_MODEL:-openai/text-embedding-3-small}
+      OPENROUTER_API_KEY: ${OPENROUTER_API_KEY}
+      API_PORT: ${API_PORT:-50700}
+      NODE_ENV: production
+      LOG_LEVEL: ${LOG_LEVEL:-info}
+    networks:
+      - hiai-docs-net
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+          cpus: "1"
+
+  web:
+    build:
+      context: .
+      dockerfile: frontend/Dockerfile
+      network: host
+    restart: unless-stopped
+    ports:
+      - "${WEB_PORT:-50701}:50701"
+    depends_on:
+      api:
+        condition: service_healthy
+    healthcheck:
+      # $$ escapes compose interpolation so WEB_PORT is resolved at runtime
+      test: ["CMD-SHELL", "wget -qO- http://127.0.0.1:$${WEB_PORT}/ || exit 1"]
+      interval: 15s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+    environment:
+      API_URL: http://api:${API_PORT:-50700}
+      PORT: ${WEB_PORT:-50701}
+      WEB_PORT: ${WEB_PORT:-50701}
+    networks:
+      - hiai-docs-net
+    deploy:
+      resources:
+        limits:
+          memory: 512M
+          cpus: "1"
+
+  caddy:
+    image: caddy:2-alpine
+    restart: unless-stopped
+    profiles:
+      - caddy
+    ports:
+      - "50708:80"
+      - "50709:443"
+    depends_on:
+      api:
+        condition: service_healthy
+      web:
+        condition: service_healthy
+    volumes:
+      - ./Caddyfile:/etc/caddy/Caddyfile:ro
+      - caddy_data:/data
+      - caddy_config:/config
+    networks:
+      - hiai-docs-net
+    deploy:
+      resources:
+        limits:
+          memory: 256M
+          cpus: "0.5"
+
+networks:
+  hiai-docs-net:
+    driver: bridge
+
+volumes:
+  pgdata:
+  redis_data:
+  ollama_data:
+  minio_data:
+  caddy_data:
+  caddy_config:

package/docs/API.md

@@ -0,0 +1,328 @@
+# API Reference
+
+Base URL: `http://localhost:50700`
+
+All responses are JSON. Errors follow `{ error: string, details?: unknown }`.
+
+## Authentication
+
+Most endpoints require a valid Better Auth session cookie. Public endpoints (health check, shared content access) are noted below.
+
+```bash
+# Sign in (sets session cookie)
+curl -X POST http://localhost:50700/api/auth/sign-in \
+  -H "Content-Type: application/json" \
+  -d '{"email": "user@example.com", "password": "secret"}'
+
+# Sign up
+curl -X POST http://localhost:50700/api/auth/sign-up \
+  -H "Content-Type: application/json" \
+  -d '{"name": "User", "email": "user@example.com", "password": "secret"}'
+
+# Get current session
+curl http://localhost:50700/api/auth/session
+
+# Sign out
+curl -X POST http://localhost:50700/api/auth/sign-out
+```
+
+## Health
+
+```
+GET /api/health           # → { status: "ok", timestamp: "..." }
+```
+
+## Documents
+
+```
+GET  /api/documents       # List (paginated)
+POST /api/documents       # Create
+GET  /api/documents/:id   # Get with tags
+PATCH /api/documents/:id  # Update (saves version)
+DELETE /api/documents/:id # Delete (cascade)
+```
+
+### List documents
+
+```bash
+curl "http://localhost:50700/api/documents?page=1&limit=20&folderId=UUID&tag=UUID"
+```
+
+Response: `{ items: Document[], total: number, page: number, limit: number }`
+
+### Create document
+
+```bash
+curl -X POST http://localhost:50700/api/documents \
+  -H "Content-Type: application/json" \
+  -d '{"title": "My Doc", "content": "Hello world", "folderId": "UUID"}'
+```
+
+### Update document
+
+```bash
+curl -X PATCH http://localhost:50700/api/documents/UUID \
+  -H "Content-Type: application/json" \
+  -d '{"title": "Updated", "content": "New content"}'
+```
+
+### Duplicate document
+
+```bash
+curl -X POST http://localhost:50700/api/documents/UUID/duplicate
+```
+
+Creates a copy with "(Copy)" suffix, including version snapshot and embedding queue.
+
+### Export document
+
+```bash
+curl http://localhost:50700/api/documents/UUID/export
+```
+
+Returns the document content as a `.md` file download.
+
+### Import document
+
+```bash
+# JSON import
+curl -X POST http://localhost:50700/api/documents/import \
+  -H "Content-Type: application/json" \
+  -d '{"title": "Imported", "content": "# Hello"}'
+
+# File upload
+curl -X POST http://localhost:50700/api/documents/import \
+  -F "file=@doc.md" \
+  -F "folderId=UUID"
+```
+
+Supports `.md`, `.txt`, `.markdown`, `.json` files (max 10 MB).
+
+### Document versions
+
+```
+GET /api/documents/:id/versions        # List version history
+GET /api/documents/:id/versions/:vid   # Get specific version
+```
+
+Versions are auto-saved on every create/update. Each entry includes `id, content, contentJson, createdBy, createdAt`.
+
+## Document Attachments
+
+```
+POST /api/documents/:id/attachments    # Upload image attachment
+GET  /api/documents/:id/attachments    # List attachments
+```
+
+Image uploads are stored in MinIO with integrity verification. Max file size: 10 MB. Only `image/*` MIME types accepted.
+
+```bash
+curl -X POST http://localhost:50700/api/documents/UUID/attachments \
+  -F "file=@screenshot.png"
+```
+
+Response includes `id, filename, mimeType, size, url` (presigned S3 URL, 24h expiry).
+
+## Collaboration (WebSocket)
+
+```
+WS /ws/collab/:documentId              # Real-time collaborative editing
+```
+
+Uses Yjs for CRDT-based conflict resolution. Authentication via query param `?token=<session_token_or_api_key>`.
+
+```bash
+# Connect via wscat (install: npm install -g wscat)
+wscat -c "ws://localhost:50700/ws/collab/DOCUMENT_ID?token=API_KEY"
+```
+
+Messages are JSON: `{ type: "sync" | "update" | "ping", update?: "base64", state?: "base64", clientId: number }`.
+
+## Webhooks
+
+```
+POST /api/webhooks/minio               # MinIO bucket event webhook
+```
+
+Verifies `x-minio-signature` header against `WEBHOOK_SECRET`. Currently handles `s3:ObjectRemoved:Delete` events to sync attachment DB records.
+
+## Folders
+
+```
+GET    /api/folders         # List (tree, root-level unless ?parentId=UUID)
+GET    /api/folders/:id     # Get single folder
+POST   /api/folders         # Create
+PATCH  /api/folders/:id     # Rename/move
+DELETE /api/folders/:id     # Delete
+```
+
+### List folders
+
+```bash
+curl "http://localhost:50700/api/folders?parentId=UUID"
+```
+
+Returns root folders when `parentId` is omitted.
+
+### Create folder
+
+```bash
+curl -X POST http://localhost:50700/api/folders \
+  -H "Content-Type: application/json" \
+  -d '{"name": "My Folder", "parentId": "UUID"}'
+```
+
+## Search
+
+```
+GET /api/search           # Full-text + semantic search (PUBLIC)
+GET /api/search/suggest   # Quick title suggestions (PUBLIC)
+```
+
+### Full search
+
+```bash
+curl "http://localhost:50700/api/search?q=query&folder=UUID&tags=tag1,tag2&dateFrom=2026-01-01&dateTo=2026-12-31&sort=relevance&page=1&limit=20"
+```
+
+Query parameters:
+
+| Param | Type | Description |
+|-------|------|-------------|
+| `q` | string | Search query |
+| `folder` | UUID | Filter by folder |
+| `tags` | string | Comma-separated tag names (ANY match) |
+| `dateFrom` | ISO date | Filter docs created after |
+| `dateTo` | ISO date | Filter docs created before |
+| `sort` | enum | `relevance`, `date_desc`, `date_asc`, `name_asc`, `name_desc` |
+| `page` | int | Page number (default 1) |
+| `limit` | int | Per page (default 20, max 100) |
+
+Response: `{ items: SearchResult[], total, page, limit }` where each item has `id, title, snippet, score, folderId, createdAt, updatedAt`.
+
+### Quick suggest
+
+```bash
+curl "http://localhost:50700/api/search/suggest?q=deploy"
+```
+
+Returns top 5 title matches with similarity scores.
+
+## Share Links
+
+```
+GET    /api/share           # List user's share links
+POST   /api/share           # Create link
+GET    /api/share/:token    # Access shared content (PUBLIC)
+DELETE /api/share/:id       # Revoke link
+POST   /api/share/:id/guests  # Add guest email
+DELETE /api/share/:id/guests/:email  # Remove guest access
+```
+
+### Create share link
+
+```bash
+curl -X POST http://localhost:50700/api/share \
+  -H "Content-Type: application/json" \
+  -d '{"documentId": "UUID", "password": "optional", "expiresIn": "7d"}'
+```
+
+Expires options: `1h`, `1d`, `7d`, `30d`, `never`.
+
+### Access shared content
+
+```bash
+# Public — no auth required. Rate limited: 10 req/min per IP.
+curl http://localhost:50700/api/share/TOKEN
+
+# With password
+curl http://localhost:50700/api/share/TOKEN \
+  -H "x-share-password: secret"
+```
+
+Returns 410 Gone if expired, 401 if password required/invalid.
+
+## Tags
+
+```
+GET    /api/tags                        # List tags with counts
+POST   /api/tags                       # Create tag
+PATCH  /api/tags/:id                   # Update tag
+DELETE /api/tags/:id                   # Delete tag
+POST   /api/documents/:docId/tags      # Tag document
+DELETE /api/documents/:docId/tags/:tagId # Untag document
+```
+
+## Agent Integration
+
+hiai-docs is designed for AI agent integration via its REST API. Use API key authentication for programmatic access.
+
+### API Key Auth
+
+Set `HIAI_DOCS_API_KEY` in your `.env` file. All API requests use Bearer token:
+
+```bash
+curl -H "Authorization: Bearer $HIAI_DOCS_API_KEY" \
+  http://localhost:50700/api/documents
+```
+
+### Semantic Search (RAG)
+
+```bash
+# Search documents by meaning (hybrid full-text + vector)
+curl -H "Authorization: Bearer $HIAI_DOCS_API_KEY" \
+  "http://localhost:50700/api/search?q=how+to+deploy+docker"
+
+# Response includes relevance scores:
+# { items: [{ id, title, content, score, rank }] }
+```
+
+### Document CRUD for Agents
+
+```bash
+# Create document
+curl -X POST http://localhost:50700/api/documents \
+  -H "Authorization: Bearer $HIAI_DOCS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"title": "Agent Note", "content": "Important finding..."}'
+
+# Read document
+curl -H "Authorization: Bearer $HIAI_DOCS_API_KEY" \
+  http://localhost:50700/api/documents/UUID
+
+# Update document
+curl -X PATCH http://localhost:50700/api/documents/UUID \
+  -H "Authorization: Bearer $HIAI_DOCS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"content": "Updated with new findings..."}'
+```
+
+### Mastra Integration
+
+```typescript
+import { Mastra } from "@mastra/core";
+
+const docsTool = {
+  name: "search_knowledge",
+  description: "Search the knowledge base for relevant documents",
+  execute: async ({ query }) => {
+    const res = await fetch(
+      `http://localhost:50700/api/search?q=${encodeURIComponent(query)}`,
+      { headers: { Authorization: `Bearer ${process.env.HIAI_DOCS_API_KEY}` } }
+    );
+    return res.json();
+  },
+};
+```
+
+## Error Codes
+
+| Code | Meaning |
+|------|---------|
+| 400  | Validation error (check `details`) |
+| 401  | Not authenticated |
+| 403  | Forbidden (not owner) |
+| 404  | Resource not found |
+| 410  | Share link expired |
+| 429  | Rate limited (check `retry-after` header) |
+| 500  | Internal server error |

package/docs/ARCHITECTURE.md

@@ -0,0 +1,75 @@
+# Architecture
+
+## Monorepo Structure
+
+```
+hiai-docs/
+├── backend/              # Elysia REST API (Bun runtime)
+│   └── src/
+│       ├── api/routes/   # Route handlers (documents, folders, search, share, tags, auth)
+│       ├── api/middleware/# Auth middleware
+│       ├── embedding/    # Embedding pipeline (chunker, providers, queue)
+│       └── lib/          # Shared utilities (db, redis, config, logger, minio)
+├── frontend/             # SvelteKit 2 + Svelte 5 + Tailwind CSS v4
+│   └── src/
+│       ├── routes/       # Pages (+page.svelte per route)
+│       └── lib/
+│           ├── components/ # UI components (sidebar, editor, cards)
+│           ├── components/ui/ # shadcn-svelte primitives
+│           └── api/      # API client functions
+├── packages/db/          # Drizzle ORM schema + migrations (shared)
+│   └── src/
+│       ├── schema.ts     # Table definitions + relations
+│       └── client.ts     # Database client
+└── docker-compose.yml    # Full stack deployment
+```
+
+## Tech Stack
+
+| Layer | Technology |
+|-------|-----------|
+| Runtime | Bun 1.3.14+ |
+| Backend | Elysia 1.4.28+ |
+| ORM | Drizzle 0.45.2+ |
+| Database | PostgreSQL 18 + pgvector |
+| Cache | Redis 8.6+ |
+| Auth | Better Auth |
+| Frontend | SvelteKit 2.60+ / Svelte 5.55+ |
+| UI | shadcn-svelte (new-york) + Tailwind v4 |
+| Editor | TipTap + svelte-tiptap |
+| Embeddings | Ollama (configurable) |
+| Storage | MinIO (S3-compatible) |
+
+## Data Flow
+
+```
+User → SvelteKit Frontend → REST API (Elysia) → PostgreSQL
+                                              → Redis (queue/cache)
+                                              → MinIO (attachments)
+                                              → Ollama (embeddings)
+```
+
+1. User creates/edits document in TipTap editor
+2. Frontend PATCHes document via API
+3. API saves content + version to PostgreSQL
+4. API enqueues embedding job to Redis
+5. Background worker fetches document, chunks text, generates vector via Ollama
+6. Worker stores vector in pgvector column
+
+Search queries run hybrid: full-text (tsvector) + semantic (pgvector cosine).
+
+## Module Boundaries
+
+- `api/` imports from `lib/` and `embedding/` — never the reverse
+- `embedding/` imports from `lib/` only
+- `lib/` has no imports from `api/` or `embedding/`
+- `packages/db/` is imported by both backend and has no dependencies on either
+
+## Security Model
+
+- **Data isolation**: every query filters by `ownerId` (user-scoped)
+- **Auth**: Better Auth session cookies (7-day expiry)
+- **Sharing**: token-based links with optional password + expiry
+- **Rate limiting**: 10 req/min per IP on public share endpoints
+- **Validation**: Zod schemas on all API inputs
+- **No secrets in code**: all config via environment variables