Skip to content
Yareta Docs

Maintenance Guide

Routine, non-incident upkeep tasks.

1. Dependency Upgrades

  • pnpm install picks up lockfile-pinned versions; review package.json’s pnpm.overrides block (currently pins vercel, @apollo/client, openai) before bumping any of those three directly — the override exists to resolve a specific conflict and a naive bump can silently break it.
  • After any dependency bump touching a large server-only package, re-check whether it needs adding to (or is already correctly excluded via) serverComponentsExternalPackages in next.config.mjs — see the NFR doc.
  • Run pnpm knip after a dependency removal/major refactor to catch now-dead code/exports (knip.config.ts scopes the check to src/** with src/auth.ts, all DB schema files, email templates, and src/queue/** as entry points).
  • wrangler version is pinned (4.78.0 at time of writing) — coordinate a bump with a check of scripts/queue-deploy.sh and both wrangler.toml variants, since Wrangler CLI behavior changes between majors have previously affected deploy scripts industry-wide.

2. Credential / Secret Rotation

Given the current secrets model (most runtime config lives as Cloudflare dashboard Variables/Secrets, set independently on the Pages project and the queue Worker — see the Infrastructure & Deployment doc), rotating any credential requires updating it in two places if both the app and the worker use it (e.g. INTERNAL_SERVICE_TOKEN, LLM provider keys used by both runtimes). A rotation that only updates one side will cause confusing partial failures (e.g. the app can call the queue’s endpoints but the queue can’t call back into the app, or vice versa).

Recommended rotation cadence and priority, in the absence of a currently documented policy:

  • OAUTH_JWT_SECRET — rotating this invalidates every outstanding OAuth access/refresh token immediately; only do this deliberately, with integrator notice if possible, since it isn’t in .env.example and its rotation isn’t currently automated.
  • AUTH_SECRET — rotating this invalidates all session JWTs (forces a platform-wide logout); treat as a break-glass action, not routine.
  • Third-party integration secrets (Stripe, LLM provider keys, CRM OAuth client secrets) — rotate per each provider’s own security recommendations; check .env.example’s categorized list for the full inventory.
  • Developer API keys / OAuth client secrets issued to third parties — these are the integrator’s own responsibility to rotate; the platform supports revoke-and-reissue (§ see the API Documentation) but doesn’t enforce an expiry today.

3. Migration Hygiene

Before generating a new migration:

  1. Pull the latest development (or production, depending on target) to get the current migrations directory state.
  2. Check the highest existing numeric prefix in src/db/migrations/ — given 24 existing numbering collisions (see the Database Documentation), coordinate with anyone else generating a migration around the same time rather than assuming drizzle-kit generate’s local numbering will be conflict-free.
  3. After merging, confirm via wrangler d1 migrations list <db> --env <env> (or the equivalent) that the migration applied as expected in each environment — don’t assume a green CI run guarantees this, since the environment/branch mapping matters.

Do not attempt a cleanup pass that renumbers or deduplicates the existing colliding migration files — they’re cumulative and already applied to live databases; renumbering would desync the directory from what’s actually been run against production. If this technical debt is ever addressed, it needs a dedicated, carefully sequenced project (e.g. squashing history into a fresh baseline for a future major version), not an incremental fix.

4. Prompt Library Maintenance

Periodically audit system_prompts (via /admin/prompts) against the corresponding code-side prompt definitions for drift — this has been a confirmed source of at least one production incident (a stale DB prompt missing a code-side safety instruction). A lightweight recurring check: for each prompt with a code-side counterpart, confirm the DB updated_at is at or after the last code change to that prompt’s file, and if not, investigate whether a sync (forceUpdatePrompts) was missed.

5. Data Migration / oneoffs Cleanup

The oneoffs pattern (pnpm oneoff:generate <name>, tracked via a DB completion marker) is for one-time scripts, not permanent code. Periodically review src/oneoffs/ (or wherever generated oneoff files land per the README’s documented convention) for scripts that have completed in all environments and can be archived or removed from the active runOneOffs() dispatch, keeping that function from growing indefinitely.

6. LLM Pricing Sync

llmPricing.source distinguishes manual from litellm_sync entries, with an isLocked flag protecting manual overrides from being clobbered by an automated sync. Periodically verify the sync job (wherever it’s scheduled — check for a litellm-related cron or admin action) is still running and that pricing hasn’t silently gone stale, since stale pricing directly affects margin calculations in the billing pipeline (see the Technical Design doc).

7. Backup Verification

Per the Disaster Recovery doc, the wrangler d1 export backup process is currently manual, triggered as a prerequisite to dev→prod merges rather than on a schedule. Until that’s automated, periodically (recommend monthly at minimum) run a manual export and confirm the resulting .sql file is non-trivial in size and parses cleanly, as a basic sanity check that backups would actually be usable if needed.

8. Dead Integration / Stub Cleanup

src/graphql/avatar-interactions/ was found to be an empty stub folder with no .ts files — worth a periodic sweep (informed by knip’s output plus manual review of src/graphql/* and src/queue/services/*) for other placeholder directories that no longer reflect active plans, to keep the domain map in the System Architecture doc accurate over time.

9. Documentation Currency

This documentation set was generated from a source-code audit and will drift the same way the older docs/*.md files did. When making an architecturally significant change (a new integration, a new deployable unit, a change to the auth model, a new vector store or LLM provider), update the relevant file(s) in the same PR — technical/architecture content lives in the sibling yareta-technical-documentation repo (technical-docs/design/, technical-docs/implementation/, technical-docs/diagrams/, and technical-docs/KNOWN-GAPS.md as the master gap tracker), and user/operational content lives in this repo (yareta-user-documentation — the README plus fourteen numbered docs, including the Quickstart, Glossary, and Integrations Setup Guide added alongside the original ten). Treat stale architecture docs as a known, previously-demonstrated risk (see §8 of the System Architecture doc) rather than a low-priority cleanup task.

Related documents: Database Documentation · Disaster Recovery / Backup · Admin Guide