Architecture

Runtime shape

Browser -> Next.js web -> signed internal request -> Fastify REST -> PostgreSQL
Claude Code -> personal bearer token -> Streamable HTTP MCP -> retrieval -> PostgreSQL

The existing Next.js root remains the web workspace so Intertool's established design system, Fumadocs surface, Auth.js integration, and accessibility primitives stay intact. The separate service and shared packages are:

apps/server          REST API and MCP endpoint
packages/contracts   Zod schemas and shared domain types
packages/db          Drizzle schema, SQL migration, seed, tenant-scoped store
packages/retrieval   deterministic ranking and context compaction
claude-plugin        plugin manifest, MCP config, skill, hook, remember command

Database

The migration creates UUID-keyed users, organizations, memberships, repositories, api_tokens, memories, memory_versions, memory_reports, and audit_events. Foreign keys and cascading behavior preserve unambiguous tenant ownership.

PostgreSQL maintains a weighted tsvector for title, content, and tags. A GIN index supports lexical search; a trigram title index is added when pg_trgm is available.

Retrieval

Candidates must be in the caller's organisation, published, unexpired, and either repository-scoped to the requested repository or organisation-wide. Type filters apply before ranking.

The explicit score combines full-text relevance, exact repository match, path match, confirmed confidence, organisation-wide applicability, source presence, age, and open reports. Ordering is stable by score, update time, then ID. Context is grouped by warnings, decisions, conventions, and remaining types, capped by count and character budget, and always keeps source and timestamp information.

Security

Fastify caps request bodies, redacts authorization/cookies from logs, rate-limits token and retrieval calls, and uses production-safe errors. Next.js applies a restrictive CSP and same-origin mutation check. Structured validators reject absolute/traversing paths, non-HTTPS sources, oversized fields, and high-confidence secret patterns.