Packages

Packages

A single npm workspace. packages/core holds the logic; everything else is an entrypoint or an adapter.

Package	Role
packages/core	All logic, organized by domain: knowledge, reference, work-items, catalog, sources, search, compliance, platform. Source-agnostic and LLM-agnostic.
packages/sources/freshdesk	Freshdesk adapter. Supports private-note write-back.
packages/sources/github	GitHub Issues adapter. Read-only (GitHub comments are public, so write-back is refused).
packages/mcp	MCP server. The primary surface for local agents (Claude Code, Copilot, Codex CLI, any MCP client). 35 tools.
packages/agent	Server-side reasoning: drives the Claude Agent SDK against the MCP server so the deployed app can reason (structure docs, consult tickets) without a local agent.
packages/api	Hono REST API plus SSE agent endpoints, auth, and the setup wizard; also serves the web UI.
packages/web	Svelte SPA: search and curate knowledge, plus a Chat that talks to the agent, plus the admin views.
packages/cli	Operational commands: sync, embed-backfill, migrate, backup, restore.
db/schema.sql	Canonical Postgres schema, with seed data. Applied wholesale on a fresh install.
db/migrations/*.sql	Incremental, idempotent migrations for upgrading an existing database. Each mirrors a change already folded into schema.sql.

core internals

packages/core/src by domain:

• knowledge/ - knowledge entries, feedback, structured-field validation.
• reference/ - freeform reference docs (chunked, embedded).
• work-items/ - ingest, raw storage, analysis runs.
• catalog/ - controlled vocabulary: components, customers, products, resolution patterns.
• sources/ - the WorkItemSource interface, the registry, connection resolution.
• search/ - hybrid search, chunking, local embeddings.
• compliance/ - PII and secret redaction.
• platform/ - DB pool, env validation, errors, logging, users, passwords, settings.

Schema vs. migrations

db/schema.sql is the source of truth for a fresh install: it always reflects the current schema, and Docker's initdb applies it once to an empty data dir. An existing database upgrades through db/migrations/*.sql (via npm run sync migrate), which are idempotent and safe to re-run. Every migration is also folded back into schema.sql, so the two never diverge (a schema-drift test guards this).

See Data Model for the schema tour.