Skip to main content

Architecture Specs

This work holds cross-feature architecture specs — deep descriptions of the substrates that user-facing features under docs/specs/features/ build on top of. Each spec targets AI agents and engineers reading the codebase and reasoning about changes, not end users.

If you're new to the platform, read in this order:

  1. pipeline-overview — wide-angle: how a generation request becomes three GitHub repositories.
  2. plugin-sdk — how plugins are loaded, selected, and given context. Almost every feature touches this.
  3. settings-system — the 3-tier resolution + x-secret hygiene contract every plugin obeys.
  4. trigger-integration — how the API hands long-running work to the Trigger.dev worker.
  5. database — the TypeORM module + repository pattern + migration policy.

Then drill into the specific subsystem(s) your work touches.

Spec Index​

The specs come in companion pairs where one is wide-angle and one is internals; both are useful but you usually want the wide-angle first.

Pipeline & generation​

SpecFocus
pipeline-overviewWide-angle: 4 pipeline categories, routing, 3-stage orchestrator
pipeline-executorInternals: state machine, step contract, modifiers, checkpointing
work-importSource-repo analyzer + the three import paths

Trigger.dev & background work​

SpecFocus
trigger-integrationAPI → Trigger.dev dispatch, payload contract, callback channel
trigger-workerInternals: per-task NestJS bootstrap, plugin hydration, logger bridge
job-runtime-providersProposed: pluggable runtime (Trigger.dev default; Temporal / BullMQ / pg-boss / Inngest) — ADR-015

Plugins & capabilities​

SpecFocus
plugin-sdk@ever-works/plugin deep-dive: capabilities, settings cascade, lifecycle
plugin-testingThe @ever-works/plugin/testing harness for plugin unit tests
settings-system3-tier setting resolution + JSON Schema x-* extensions
ai-facadeAiFacadeService routing, model catalog, retry & cost tracking

Auth, audit, and access​

SpecFocus
authJWT + OAuth + API keys + device flow
activity-logAudit + per-feature changelog infrastructure

Data & state​

SpecFocus
databaseTypeORM module, repository pattern, forward-only migrations
cacheThe cache_entries table and its 4 consumers (locks, checkpoints, AI cache, model catalog)
events@nestjs/event-emitter + BaseEvent contract

Surfaces​

SpecFocus
web-dashboardNext.js 16 App Router internals — routing, layouts, server actions
cliPublic CLI + internal-cli architectures
mcp-server-internalsOpenAPI → MCP tool conversion + sanitiser

Operations​

SpecFocus
deploymentDocker + Kubernetes + Compose + env-var contract
monitoringSentry + PostHog + structured logging
notifications-mailIn-app + email delivery
subscriptionsPlans, usage ledger, billing-provider plugin contract

Companion Pairs​

Some specs are intentionally split into a wide-angle view + an internals deep-dive. Read the wide-angle first:

Wide-angleInternals
pipeline-overviewpipeline-executor
trigger-integrationtrigger-worker
plugin-sdkplugin-testing

Conventions​

Every architecture spec in this work follows the same shape:

# Architecture: <Subject>

**Status**: `Active` | `Draft` | `Deprecated`
**Last updated**: YYYY-MM-DD
**Audience**: <one-sentence audience description>

---

## 1. Purpose

## 2. <Domain-specific sections>

...

## N. References / See Also

Specs ground every claim in a real file path or class name from the current develop branch — no speculation, no aspirations. When the code changes, the spec changes; when the spec is wrong, file an ADR under docs/specs/decisions/ explaining why.

When a spec needs to change​

  1. The code changed → update the spec in the same PR.
  2. The architecture should change → write an ADR under docs/specs/decisions/, land it, then update the spec to match the new reality.
  3. You found the spec wrong on develop → fix it directly; no ADR needed for documentation drift.