Skip to content

Core & State Docs

Use docs/core for stable “what the system is” docs, and docs/state for operational maps that help future implementation work start quickly.

docs/core/
  ProductModel.md
  SystemArchitecture.md
  PresentationVideoWorkflow.md
  PresentationConfig.md
  MastraAgentsAndTools.md
  RagAndSources.md
  PayloadDataModel.md
  AuthAndWorkspace.md
  BillingAndEntitlements.md
  WorkersAndJobs.md
  TestingAndVerification.md

What Each Core Doc Should Cover

ProductModel.md - What Anuva is - Product surfaces - Presentation Video concept - what is intentionally not supported - user-facing terminology

SystemArchitecture.md - app topology - Next.js/Payload/Mastra relationship - frontend/backend/admin surfaces - key runtime dependencies - high-level data flow

PresentationVideoWorkflow.md - current Presentation Video creation flow - Mastra workflow sequence - human-in-the-loop boundaries - generated artifacts - edit/regeneration behavior - preview/final video readiness

PresentationConfig.md - PresentationCompilationConfig - public config shape - scene model - Reveal slide model - audio/media/direction fields - preview/render config invariant

MastraAgentsAndTools.md - agents - subworkflows - tools - model/provider configuration - memory usage - metering hooks - deterministic boundaries

RagAndSources.md - source types - upload/website/web research/RSS status - ingestion flow - retrieval flow - workspace scoping - source usage in Presentation Video

PayloadDataModel.md - important collections - relationships - schema ownership - generated files - schema-change checklist

AuthAndWorkspace.md - Better Auth setup - workspace resolution - access-control rules - server action pattern - tenant-boundary rules

BillingAndEntitlements.md - plans - wallets - Gold/Silver coin behavior - AI metering - content entitlements - payment provider integration

WorkersAndJobs.md - RAG worker - presentation worker - generation jobs - render jobs - retries/status/progress - required env vars

TestingAndVerification.md - which tests exist - when to run each command - mocks/harnesses - e2e setup - docs parity checks

docs/state/
  CurrentImplementationMap.md
  RouteMap.md
  ServerActionsMap.md
  WorkflowMap.md
  CollectionMap.md
  EnvAndServices.md
  ScriptsAndCommands.md
  KnownGaps.md
  RecentDecisions.md
  DocsUpdateChecklist.md

What Each State Doc Should Cover

CurrentImplementationMap.md - fast orientation map - “start here” pointers - current canonical paths - deprecated/legacy paths to avoid

RouteMap.md - public routes - app routes - API routes - Payload routes - route ownership and key files

ServerActionsMap.md - action files - main exported actions - auth/workspace pattern - mutation responsibilities

WorkflowMap.md - Mastra workflows - subworkflows - step order - inputs/outputs - linked agents/tools

CollectionMap.md - Payload collections - purpose of each - key relationships - workspace-scoped vs global

EnvAndServices.md - required .env keys - hosted vs local services - provider keys - storage/email/database assumptions

ScriptsAndCommands.md - seeders - workers - diagnostics - generation scripts - common command recipes

KnownGaps.md - current limitations - temporarily disabled capabilities - partial implementations - risky areas

RecentDecisions.md - architecture/product decisions - date, decision, reason - links to change folders

DocsUpdateChecklist.md - what docs to update by change type - stale-term scan examples - generated-file reminders

How They Should Be Used

For every small or large change:

  • update docs/core if durable system behavior changed
  • update docs/state if implementation location, commands, gaps, or operational flow changed
  • update docs/changes/<change> for why that specific change happened