Development

This section is the reviewable source for how Riviamigo is structured, implemented, and reviewed. Start with contributor orientation, then follow the subsystem or governance path that owns the work. Deployment and recovery procedures live in Operations; lookup-oriented contracts live in Reference.

Contributor orientation

• Contributing defines review, documentation, testing, security, and pull-request expectations.
• AGENTS.md is the primary bootstrap and repository policy for repo-aware agents.
• CLAUDE.md is the concise command and execution companion.
• Architecture overview maps application and package ownership.

The usual local entrypoints are:

pnpm run dev:stack
pnpm typecheck
pnpm lint
pnpm test
pnpm docs:check
pnpm docs:build
pnpm verify:migration-integrity

The development and production Compose stacks both use PostgreSQL 18 with TimescaleDB 2.28.3, but they use separate volumes and data layouts. Keep the development volume separate from production data.

pnpm dev:stack also starts the local restore supervisor alongside the host-run API. Its capability key is generated under the ignored data/ directory, while backup artifacts continue to use the local /backups path. This keeps the in-app restore path testable without putting development credentials or restore data in Git. Vite proxies restore-runtime status requests directly to that supervisor so the status poll can survive the API process restart.

The launcher builds only the API and restore-supervisor binaries that it runs; maintenance binaries remain available through their explicit Cargo commands. On Windows it limits that build to four concurrent Cargo jobs to keep the host responsive. Set DEV_CARGO_BUILD_JOBS to a positive integer when a different limit is appropriate for the machine.

Architecture

• Backend data flow follows Rivian connectivity, ingestion, storage, and API delivery.
• Dashboard architecture explains shared page shells, renderers, widgets, and editor ownership.
• Rivian authentication documents connection and upstream-auth behavior.

Implementation guidance

• Dashboard authoring
• Brand and visual system
• Security

Governance and review

• Documentation maintenance defines the publication and documentation-impact contract.
• Security audit records security review scope and current evidence.
• Decision log captures durable architectural and workflow choices.
• Roadmap records project direction and parity goals.

Exact references

Use Reference for API access, metric definitions, and the dashboard data map. Keeping these lookup pages separate prevents architecture and contributor guidance from becoming dense contract inventories.

Every non-trivial change declares documentation impact, updates the owning docs with the implementation, and records focused verification close to the changed seam.

Database migration changes also require the migration-integrity check and the restore compatibility contract checks. Add only immutable LF/UTF-8 migrations after the public baseline; use the explicit adoption runbook for an intentional chain cutover.