Contribution Guidelines

These guidelines are aimed at keeping work in this repository consistent across the frontend, backend, and operational layers.

Contribution Workflow

Start from a focused branch.
Keep the change set tight around one feature, bug fix, or documentation task.
Update tests or docs when behavior changes.
Run the relevant validation commands before opening a review.

Frontend Conventions

App routes live in stitch/frontend/src/app.
Reusable product UI lives in stitch/frontend/src/components.
API clients and integration helpers live in stitch/frontend/src/lib.
Prefer fitting new work into the existing route groups and shared component system rather than duplicating patterns.

Backend Conventions

Keep HTTP routing readable and explicit.
Put reusable domain behavior in stitch/backend/services instead of growing route handlers further.
Add focused controllers when a domain area deserves its own router, as already done for billing and chat.
Keep Pydantic models explicit and aligned with the API surface.

Database and Data Changes

Schema snapshots live in stitch/backend/supabase_schema.sql.
Incremental changes should be added in stitch/backend/migrations.
If a feature depends on recommendations or academic knowledge, update the corresponding sync or ingestion flow as part of the same change.

Design and Prototyping

Non-runtime stitched prototypes in stitch/ are useful references when implementing new product surfaces.
Experimental work should stay isolated in experiments/ until it is ready to move into the production runtime.

Validation Checklist

Run the commands that match your change:

cd stitch/frontend
npm run lint

cd stitch/backend
pytest

cd docs
make html

Documentation Expectations

If you add a new major route group, backend capability, worker, or integration, update the matching documentation page in this docs/ tree so the site stays useful as a project handbook.