Caret’s local development environment runs as a set of containerised services orchestrated by Docker Compose. A single command brings up the React/Vite frontend, the Express API Gateway, three specialised Node backend services, and the FastAPI AI service — all wired together and connected to a Supabase Cloud database. You can also run any individual service outside of Docker for tighter iteration cycles, using Bun for Node/frontend work and uv for the Python AI service.Documentation Index
Fetch the complete documentation index at: https://mintlify.com/arrozet/caret/llms.txt
Use this file to discover all available pages before exploring further.
Prerequisites
Before you begin, make sure the following tools are installed on your machine.Docker + Docker Compose
Required to run the full stack. Docker Desktop includes Compose on macOS and Windows. On Linux, install the Docker Engine and the Compose plugin separately.
Git
Required to clone the repository and manage branches during development.
Bun
Optional — only needed if you want to run the frontend or Node backend services directly outside of Docker. Install from bun.sh.
uv
Optional — only needed if you want to run the Python AI service directly outside of Docker. Install from docs.astral.sh/uv.
Quick Start
Create your .env file
Copy the minimal template below into a file named See the Environment Variables reference for the full list of available variables.
.env at the repository root and fill in your Supabase and OpenAI credentials:Build and start all services
Open the app
Once all health checks pass, open http://localhost:5173 in your browser. The API Gateway is available at http://localhost:3000.
Service Ports
Each service exposes a fixed port locally. Internal-only services are still reachable on the host for debugging, but the frontend only communicates with the API Gateway and the Collab service directly.| Service | Port | Notes |
|---|---|---|
| Frontend | 5173 | React/Vite with hot-reload |
| API Gateway | 3000 | Proxies all /api/v1/... traffic |
| Auth Service | 3001 | Reached only by the Gateway |
| Document Service | 3002 | Reached only by the Gateway |
| Collab Service | 3003 | Direct WebSocket — frontend connects here |
| AI Service | 8000 | FastAPI — reached via Gateway at /api/v1/ai |
Running Services Individually (Without Docker)
For tight feedback loops — such as when iterating on a single service — you can run it directly on your host while keeping everything else in Docker. Stop the relevant container first (docker compose stop <service>), then start the service manually.
Frontend
http://localhost:5173 with full hot module replacement.
Node Backend Services
Each Node service follows the same pattern:AI Service (Python/FastAPI)
Package Manager Rules
Caret enforces strict package manager usage. Deviating from these rules will cause CI failures and may break Docker builds.| Ecosystem | Required | Never use |
|---|---|---|
| Frontend (React/Vite) | Bun | npm, yarn, pnpm |
| Node backend services | Bun | npm, yarn, pnpm |
| Python AI service | uv | pip, poetry, pipenv |
Common Development Commands
The following commands are available in each service directory. Use them for focused work on a single service, or use the Makefile targets listed below to run them from the repo root.Frontend and Node Services
| Command | Purpose |
|---|---|
bun run dev | Start the development server with hot-reload |
bun run build | Compile TypeScript and build production assets |
bun run test:unit | Run unit tests with Vitest |
bun run test:integration | Run integration tests |
bun run lint | Lint source files with ESLint |
bun run format:check | Check formatting with Prettier |
bun run openapi:generate | Regenerate swagger.json from tsoa controllers (Gateway, Auth, Document services) |
AI Service (Python)
| Command | Purpose |
|---|---|
uv run uvicorn src.main:app --reload --port 8000 | Start with auto-reload |
uv run pytest | Run all tests |
uv run ruff check . | Lint with Ruff |
uv run pyright | Run static type checks |