Development guide

SaaSWeave ships the same repo-specific guidance its maintainers and coding agents work from. These pages document the current preferred way to build things in this codebase, from transport and state to logging and tests. They are mirrored from the .agents/ directory in the repository, which stays the single source of truth.

Open the most specific page first, then follow its links only when a task crosses into another concern.

Working in the codebase

• Workflow: fix cadence, validation scope, build checks, migrations, commits.
• Vite Plus toolchain: vp and vpx, workspace scripts, package management.
• TypeScript conventions: typing rules and patterns used throughout the repo.
• Testing: focused unit and end-to-end coverage and test command scope.

Backend

• Core contracts: pure shared contracts and security limits.
• Environment variables: validated configuration schemas.
• Auth patterns: Better Auth on the server, client, and SSR.
• oRPC patterns: procedures, routers, and client integration.
• API fetching patterns: query and mutation conventions.
• Logging: durable logs, request logging, redaction.
• Media storage: uploads, delivery, and storage lifecycle.
• End-to-end features: how a feature threads through every layer.

Frontend

• TanStack patterns: Router and Query usage in the web app.
• Zustand state: client state stores and conventions.
• UI components: the shared component library and theme tokens.
• Internationalization: Paraglide messages and localized routing.
• SEO: route metadata helpers.

Agent skills

The repository packages a couple of task-scoped playbooks as agent skills under .agents/skills/. Each skill is a thin activation wrapper (when to use it and a short procedure); the durable knowledge lives in reference docs that read as standalone engineering guides. Those reference docs are below.

• Building a feature end-to-end: every cross-cutting surface a new toggleable feature touches, with the concrete repo pattern for each.
• Redis, queues, and caching: package boundaries and the cache, queue, and retention patterns.