Development
Repository development workflows and implementation notes.
The OrcAI repository is a Bun workspace with applications under apps/* and shared packages under packages/*.
Main applications
apps/app: main OrcAI application.apps/workers: background worker process.apps/web: website and documentation service.apps/e2e: Playwright end-to-end suite, see End-to-end tests.
Architecture lists the shared packages.
Recommended workflow
Run bun install --frozen-lockfile, then bun run stack up. This starts an isolated Docker Compose project for the checkout, writes a gitignored .env with per-worktree ports, applies migrations, and applies the SpiceDB schema. SeaweedFS creates the object storage buckets on startup. Start the app with bun run stack dev or everything with bun run stack dev --all. Several checkouts or worktrees can run at the same time without port conflicts.
The repository also includes a VS Code devcontainer that provides the same infrastructure inside Compose. The container keeps its own environment in .devcontainer/.env, never the checkout's .env, and bun run dev:all serves the app on port 3000 and the docs on 3001. For details on either path, see the README and the Commands page.
Developer pages
Commands
Common Bun workspace commands for apps, workers, checks, database migrations, and docs.
Architecture
How app, workers, storage, authorisation, retrieval, and AI services fit together.
Localisation
How copy is translated, named, and found by tests.
Glossary
The product terms in English and German.
End-to-end tests
Running the Playwright suite, how a run resets and isolates data, the fixtures, and the slice rules.
Contributing
Branching, commit format, local validation, pull request expectations, and docs conventions.