Local Development¶

This runbook covers setting up the Curaway backend and frontend for local development.

Prerequisites¶

Backend Setup¶

1. Clone the Repository¶

git clone https://github.com/your-org/curaway_src.git
cd curaway_src

2. Create the Environment File¶

cp .env.example .env

Edit .env and fill in the required values. See the configuration reference for all variables. At minimum, you need:

• DATABASE_URL -- PostgreSQL connection string
• OPENAI_API_KEY -- For LLM and embeddings
• CLERK_SECRET_KEY -- For JWT validation (or set AUTH_DISABLED=true)

For local development with auth disabled:

AUTH_DISABLED=true
APP_ENV=development
LOG_LEVEL=DEBUG

3. Set Up a Virtual Environment¶

python -m venv .venv
source .venv/bin/activate  # On macOS/Linux
# .venv\Scripts\activate   # On Windows

4. Install Dependencies¶

pip install -e ".[dev]"

This installs the application in editable mode along with development dependencies (pytest, ruff, mypy, etc.).

5. Run Database Migrations¶

alembic upgrade head

This applies all pending Alembic migrations to your PostgreSQL database. See the database operations runbook for more details.

6. Seed the Database¶

python -m app.seed

This runs the base seed (tenant + consent records). For a fully populated local environment, run the full seed sequence described in the seed data runbook.

7. Start the Development Server¶

uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

The server will start at http://localhost:8000 with auto-reload enabled. The interactive API docs are available at:

• Swagger UI: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc
• OpenAPI JSON: http://localhost:8000/openapi.json

8. Verify the Server Is Running¶

curl http://localhost:8000/ready

Expected response:

{"status": "ok"}

Frontend Setup¶

1. Navigate to the Frontend Directory¶

The frontend is in a separate repository or directory (depending on your setup):

cd curaway-frontend  # or the appropriate directory

2. Install Dependencies¶

npm install

3. Create the Environment File¶

cp .env.example .env.local

Key frontend environment variables:

NEXT_PUBLIC_API_URL=http://localhost:8000/api/v1
NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_xxxx
CLERK_SECRET_KEY=sk_test_xxxx
NEXT_PUBLIC_FLAGSMITH_API_KEY=xxxx

4. Start the Development Server¶

npm run dev

The frontend will start at http://localhost:3000 with hot module replacement enabled.

Running Tests¶

Backend Tests¶

# Run all tests
pytest

# Run with coverage
pytest --cov=app --cov-report=html

# Run a specific test file
pytest tests/test_cases.py

# Run tests matching a keyword
pytest -k "test_patient_create"

# Run with verbose output
pytest -v

Linting and Type Checking¶

# Lint with ruff
ruff check .

# Auto-fix lint issues
ruff check --fix .

# Type checking with mypy
mypy app/

Frontend Tests¶

# Run all tests
npm test

# Run in watch mode
npm run test:watch

Local Services via Docker (Optional)¶

If you want to run databases locally instead of using managed staging instances:

# PostgreSQL
docker run -d \
  --name curaway-postgres \
  -e POSTGRES_USER=curaway \
  -e POSTGRES_PASSWORD=curaway \
  -e POSTGRES_DB=curaway \
  -p 5432:5432 \
  postgres:16

# Neo4j
docker run -d \
  --name curaway-neo4j \
  -e NEO4J_AUTH=neo4j/curaway123 \
  -p 7474:7474 \
  -p 7687:7687 \
  neo4j:5

# Qdrant
docker run -d \
  --name curaway-qdrant \
  -p 6333:6333 \
  qdrant/qdrant:latest

Then update your .env accordingly:

DATABASE_URL=postgresql+asyncpg://curaway:curaway@localhost:5432/curaway
NEO4J_URI=bolt://localhost:7687
NEO4J_USERNAME=neo4j
NEO4J_PASSWORD=curaway123
QDRANT_URL=http://localhost:6333

Common Development Tasks¶

Adding a New Endpoint¶

1. Create or update the route in app/api/v1/routes/.
2. Add Pydantic request/response schemas in app/schemas/.
3. Add business logic in app/services/.
4. Write tests in tests/.
5. Run pytest and ruff check . to validate.

Adding a New Alembic Migration¶

alembic revision --autogenerate -m "Add description of change"
alembic upgrade head

Resetting the Local Database¶

alembic downgrade base
alembic upgrade head
python -m app.seed

Updating Dependencies¶

pip install -e ".[dev]"  # After modifying pyproject.toml

IDE Setup¶

VS Code (Recommended)¶

Install these extensions:

• Python (ms-python.python)
• Pylance (ms-python.vscode-pylance)
• Ruff (charliermarsh.ruff)
• ESLint (dbaeumer.vscode-eslint)

Recommended settings.json:

{
  "python.defaultInterpreterPath": ".venv/bin/python",
  "python.analysis.typeCheckingMode": "basic",
  "[python]": {
    "editor.defaultFormatter": "charliermarsh.ruff",
    "editor.formatOnSave": true
  }
}