Skip to main content

Shared packages

Reusable infrastructure lives under packages/. Apps depend on these; apps never depend on each other.

PackagePurpose
@constellation-platform/auth-coreJWT types, clearance levels, permission checking
@constellation-platform/auth-nextNext.js auth middleware (withAuth, withTenantAuth, locale primitives)
@constellation-platform/dbTenant-scoped Prisma client, RLS helpers, auditAction() for routine audit, correlation-id propagation
@constellation-platform/design-tokensThe Constellation design language (warm-neutral OKLCH foundation, single amber accent, functional status colours, Geist type) + a Path A bridge aliasing every shadcn variable onto a Constellation token, Tailwind v4 @theme mapping, light/dark palettes, and a11y baseline (prefers-reduced-motion, :focus-visible). CSS-only — import styles.css from each app's globals.css.
@constellation-platform/errorsStandard error hierarchy and API envelope (AppError, toErrorResponse)
@constellation-platform/auditTransactional audit via outbox (auditCritical() — writes audit row + publishes audit.entry.created event in the same txn)
@constellation-platform/eventsOutbox-based event publishing (publish), polling dispatcher, subscribe
@constellation-platform/jobsJob queue abstraction (createJobQueue({ type: 'postgres' | 'memory', ... })). Two implementations today: PostgresJobQueue (durable) and InMemoryJobQueue (tests)
@constellation-platform/storageObject-storage adapter. S3-compatible (MinIO in dev, S3 in cloud, MinIO on-prem) plus a Supabase Storage backend for Supabase-hosted tenants
@constellation-platform/i18nBCP-47 Locale type, resolveLocale(), Intl format helpers
@constellation-platform/translationAI-backed translation; wraps ai-core
@constellation-platform/ai-coreProvider-agnostic LLM abstraction (Claude / mock); audit + budget
@constellation-platform/ai-embeddingsEmbedding-API provider abstraction (OpenAI / mock); pgvector-friendly output
@constellation-platform/ai-ragRetrieval-augmented generation primitives — combines ai-core and ai-embeddings for grounded responses
@constellation-platform/coordinatorHosted reasoning service — stateless consultCoordinator() over programme-scoped Project Tracker state; persists every consult to coordinator.consults and emits an audit entry via auditCritical. Phase 1: engine only; MCP tool deferred to PLT-171.
@constellation-platform/testingTest tenant/user factories, test transaction wrapper
@constellation/contractsShared Zod schemas and derived types (cross-module event payloads, common shapes)
@constellation-platform/uiShared React components (incl. LocaleSwitcher)
@constellation-platform/coordinator-chatShared coordinator UI rendered by Project Tracker as both the full-page workspace (CoordinatorWorkspace) and the task drawer (PLT-224, PLT-237). Zone-agnostic transport via an injected resolveApiUrl. Consumed as source.
@constellation/configShared ESLint, TypeScript, Vitest configs

i18n entry points​

Internationalisation primitives are split across three packages so apps can compose only what they need:

  • @constellation-platform/i18n — runtime-agnostic. Locale union, SUPPORTED_LOCALES, resolveLocale(), negotiateAcceptLanguage(), formatDate/DateTime/Number/Currency, message-loader with regional → base-language → default fallback, and a localized() JSONB overlay reader.
  • @constellation-platform/auth-next/locale — Next.js wiring. Cookie helpers (readLocaleCookie, serializeLocaleCookie, clearLocaleCookieValue), edge-middleware integration via the localeResolver option on createConstellationAuthMiddleware, withVaryCookie() response decorator, and AuthContext.locale populated by withAuth.
  • @constellation-platform/translation — AI translation. TranslationProvider interface and createTranslationProvider({ ai, model }) that wraps ai-core so tenant budget + audit are inherited.
  • @constellation-platform/ui — shared LocaleSwitcher client component (server-action driven; renders null when fewer than two locales are enabled).

See Multilanguage (i18n) for the architecture overview.

When to use which​

  • AI features. Start with @constellation-platform/ai-core for provider-agnostic completion calls (with budget + audit). Add @constellation-platform/ai-embeddings when you need vector embeddings (semantic search, RAG retrieval). Add @constellation-platform/ai-rag when you want grounded answers — it composes ai-core + ai-embeddings and handles the retrieval / context-injection wiring. For programme-scoped reasoning over live PT + GitHub state (prioritisation, duplicate-effort detection, "what next"), call @constellation-platform/coordinator's consultCoordinator() — it wraps ai-core and writes an append-only coordinator.consults row plus a coordinator.consult.created audit entry per call.
  • Persistence. @constellation-platform/db for any tenant-scoped DB access. Use withTenantContext() to open a transaction with app.tenant_id set. Use auditAction() for routine audit; reach for @constellation-platform/audit's auditCritical() only when the mutation must publish an audit.entry.created outbox event for downstream SIEM.
  • Async work. @constellation-platform/jobs for one-off background work. @constellation-platform/events for cross-module domain events (always wrap in the originating transaction).
  • Files. @constellation-platform/storage (S3 / MinIO).
  • Auth. Apps wire @constellation-platform/auth-next and call into @constellation-platform/auth-core for permission helpers.
  • UI. Always import from @constellation-platform/ui, never from app-local components/ui/.