Developer Setup

Developer Setup

This page documents supported contributor setup and advanced debug workflows.

When To Use This Page

Use this page when you need to set up a contributor environment, choose a run mode, or extend backend integration behavior.

Audience

• Contributors working on project-code/backend or project-code/frontend.
• Maintainers validating local developer environments before CI.

Setup Path A: Dev Container (Recommended)

From repository root:

cd project-code

1. Open in VS Code.
2. Reopen in container.
3. Wait for post-create setup to finish.

Expected post-create behavior:

• Backend dependencies via uv sync --all-packages --all-groups --frozen
• Frontend dependencies via package manager install
• Tooling availability for lint/test workflows

Setup Path B: Local Tooling (No Dev Container)

Backend dependencies

From project-code/backend:

uv sync --all-packages --all-groups

Frontend dependencies

From project-code/frontend:

npm install

If your lockfile policy is yarn-based:

yarn install

Run Modes (Choose One Intentionally)

Mode 1: Full stack in containers (baseline)

From project-code/:

docker compose up -d --build

Use this mode for parity with documented local operations.

Mode 2: Frontend on host, backend in containers

1. Start backend stack from project-code/.
2. Start frontend from project-code/frontend:

npm run dev

3. Ensure frontend points to host-reachable gateway (VITE_API_URL=http://localhost:8000 for host runtime).

Mode 3: Backend quality loop (fast feedback)

From project-code/backend:

uv run python -m ruff check .
uv run python -m pytest -q

Host vs Container Environment Expectations

Concern	Host Runtime	Container Runtime
Gateway URL for frontend	Usually http://localhost:8000	Usually service DNS (http://api-gateway:8000)
DB host variables	localhost style when services exposed to host	service names like timescaledb
Log access	host process stdout	docker compose logs -f <service>
Network assumptions	host ports must be open/mapped	compose service DNS available

If requests fail after switching mode, re-check VITE_API_URL and CORS values first.

IDE Attach / Container Debug Patterns

VS Code + Dev Container

1. Ensure stack is running.
2. Open service logs in terminal:

docker compose logs -f api-gateway tactic-middleware

3. Run tests from integrated terminal for reproducible breakpoints:

cd project-code/backend
uv run python -m pytest -q

PyCharm + Docker Compose interpreter (advanced)

• Use compose-based interpreter for backend module execution.
• Keep compose env parity with project .env.
• Prefer service log inspection over IDE-only stdout when investigating orchestration issues.

Contributor Workflow: Extend Charger API Provider

Use this path when adding a new upstream charger provider without changing business logic contracts.

1. Implement provider client conforming to existing charger client protocol interface.
2. Add provider config model with strict validation for provider-specific settings.
3. Register provider in central dependency resolver switch.
4. Add settings/env wiring for provider selection and credentials.
5. Add tests:

• unit tests for provider client behavior
• integration test that injects provider into sync path

Minimum acceptance for provider extension:

• Existing provider still works unchanged.
• New provider selectable by environment variable.
• Sync services operate without service-layer refactor.

Pre-Commit And Local Quality Gate

From project-code/:

pre-commit install
pre-commit run --all-files

From project-code/backend:

uv run python -m ruff check .
uv run python -m pytest -q

From project-code/frontend:

npm run lint
npm run test

Failure-Oriented Setup Triage

Symptom	Likely Cause	First Fix
Frontend cannot call API in host mode	VITE_API_URL still container DNS	set VITE_API_URL=http://localhost:8000
Gateway restarts during boot	DB sync/schema not ready	wait, then inspect db-sync + gateway logs
Monitoring endpoints return upstream errors	TACTIC not ready or Docker API connectivity issue	check http://localhost:8001/ready and TACTIC logs
Pre-commit fails unexpectedly	local env drift vs lock state	rerun dependency sync and rerun hooks

Related Pages

• Getting Started
• Architecture Overview
• Environment Variables
• Testing & Debugging
• Contributing & CI