Local development setup

ScaiWave is a Python 3.12+ FastAPI backend plus a SolidJS frontend wrapped by Tauri. You can run the whole thing locally; tests use SQLite in-memory so no infrastructure is needed for those.

Prerequisites#

• Python 3.12 or newer.
• Node 20 or newer (for the client).
• Docker + Docker Compose (for the infra layer).
• (Optional) Rust toolchain if you want to build the Tauri desktop app.

1. Clone and set up the venv#

1
2
3
4
5

git clone https://github.com/scailabs/scaiwave.git
cd scaiwave
python3.12 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/pip install -e docs/integrations/scaidrive/sdk-python

The editable ScaiDrive SDK install is needed for the drive plugin to work; otherwise drive-search returns an import error.

2. Start the infra#

1

make docker-up

Spins up MariaDB, Redis, NATS JetStream, MinIO, Weaviate, and ClamAV. Default ports are configured in docker-compose.yml.

Wait until docker-compose ps shows all services healthy.

3. Run migrations#

1

make migrate

Applies every Alembic migration to the dev database. Idempotent.

4. Start the API#

1

make dev

Hot-reload FastAPI on :8000. The default config uses auth_mode=mock — sign in returns a static token without a real ScaiKey, so you can develop without setting up identity.

Watch the logs in this terminal.

5. Start the worker#

In another terminal:

1

make worker

ARQ async worker for background jobs: message indexing, summary generation, scheduled tasks, sidekick timeouts.

6. Start the client#

In another terminal:

1
2
3

cd client
npm install
npm run dev

Vite dev server on :5173. The dev proxy forwards /v1/* and /_scaiwave/* to the API on :8000.

Open http://localhost:5173 — you'll be auto-signed-in as the mock dev user.

7. (Optional) Tauri desktop#

1
2

cd client
npm run tauri:dev

Launches the Tauri desktop app pointing at the dev server. Native windows, native notifications, OS-level keychain for tokens.

Running tests#

1

make test

Runs pytest with asyncio_mode=auto. Uses SQLite in-memory — no infra required.

Specific file:

1

.venv/bin/pytest tests/unit/test_room_service.py -v

Specific test:

1

.venv/bin/pytest tests/unit/test_room_service.py::TestCreateRoom::test_dm_resolves_per_viewer -v

Linting#

1

make lint

Runs ruff. CI rejects unfixed lints.

Generating a migration#

After changing a SQLAlchemy model:

1

make migration msg="add new field to participants"

Alembic autogenerates a migration in app/db/migrations/versions/. Review the SQL before applying.

Where to go next#

• Authenticate with ScaiKey.
• Your first REST API call.
• Reference: Configuration — every env var.
• Reference: CLI.