Riff Environment

Architecture at a glance

Riff apps are React frontends + Python backends running on Riff’s production-grade infrastructure. The Agent plans tasks, edits code, runs tests, and deploys in one workspace.

Frontend: React pages and components. Backend: FastAPI endpoints plus reusable libs.

Where things live:

• frontend/src/pages/* (routes)

• frontend/src/components/* (UI)

• backend/app/apis/* (POST/GET endpoints)

• backend/app/libs/* (helpers)

Environments & Deploys

• Dev vs Prod: Build and test in the workspace (Preview). Deploy to make changes live.

• Rollbacks & logs: Use Preview logs while developing; schedule runs include execution history.

Authentication & Access

• Built-in auth (Stack Auth): sign-in/out, sessions, protected routes.

• Protecting endpoints: toggle page/API auth (shield icon) from the Code Editor / Access.

Data: Database vs Storage

• Database (Postgres): versioned migrations, separate dev/prod DBs, query in-app.

• Storage (files, dataframes): persistent, backend-only; ideal for CSVs, images, PDFs.

• Rule of thumb: structured data → DB; large/binary files → Storage.

Secrets & Configuration

• Store API keys and credentials in Secrets (never in code).

• Access via environment variables in backend; scope to dev/prod as needed.

Scheduling & Background Work

• Create cron schedules that POST backend endpoints; choose dev or prod runtime; monitor history and pause/resume.

Integrations & Webhooks

• Native integrations: OAuth once, agent verifies scopes and runs a test call.

• Custom APIs: the agent defines endpoints, handles pagination/retries, sets webhooks, and verifies signatures.

• Webhooks: ensure target endpoints are public (auth gate off if required) and deployed when testing third-party callbacks.

Packages & SDKs

• The agent installs npm/pip packages as needed; view versions in Packages.

• Frontend packages are for React only; Python packages for backend only.

Observability & Troubleshooting

• Preview logs and schedule run logs for quick diagnosis.

• Use Tasks history to see agent reasoning, diffs, and decisions.

Limits & Best Practices

• Keep long-running or sensitive work in backend APIs.

• Avoid storing secrets in frontend; prefer server-side calls for third-party APIs.