Skip to content

🛠️ Everyday Command Center

Reference cheat sheet for daily development workflows, debugging, container management, and Git operations.

1. Service Orchestration

All primary services can be launched via root Makefile targets or directly inside their respective application directories:

Action Makefile Target (Root) Direct Subdirectory Command Description
Start DB & Telemetry make up docker compose -f deploy/docker-compose.yml up -d Starts Postgres 16, Vector, and VictoriaLogs.
Stop All Containers make down docker compose -f deploy/docker-compose.yml down Gracefully shuts down containers.
Run API Backend make run-api cd apps/api && go run cmd/server/main.go Starts Go REST API on http://localhost:8080.
Run Frontend UI make run-web cd apps/web && npm run dev Starts Vite dev server on http://localhost:5173.
Run Async Worker make run-worker cd apps/worker && .venv/bin/python src/main.py Starts Python Outbox polling worker.
Run Documentation make docs-serve zensical serve Starts live docs server on http://127.0.0.1:8000.

2. Monorepo Tree Inspection

Use this filtered tree command to view the file hierarchy up to 8 levels deep without cluttering output with virtual environments, build artifacts, or package caches:

# 8-level deep repository tree (excluding node_modules, .venv, git, etc.)
tree -L 8 -I "vendor|.git|__pycache__|.venv|venv|bin|node_modules|storage|.idea|.vscode|dist|build" .

# Directory-only view (8 levels deep)
tree -d -L 8 -I "vendor|.git|__pycache__|.venv|venv|bin|node_modules|storage|.idea|.vscode|dist|build" .

3. Docker & Telemetry Management

# View active container status, ports, and health checks
make ps
# or: docker ps --format "table {{.Names}}\t{{.Status}}\t{{.Ports}}"

# Inspect live container logs (e.g. Postgres or Vector)
docker logs -f dues_postgres
docker logs -f dues_vector

# Open interactive PostgreSQL shell inside the container
docker exec -it dues_postgres psql -U dues_admin -d dues_db

# Reset and purge database volume (caution: wipes local DB data)
docker compose -f deploy/docker-compose.yml down -v
make up

📊 Telemetry Dashboard: VictoriaLogs UI is accessible at http://localhost:9428/select/vmui. Filter logs using service:dues_postgres or level:ERROR.

4. Git Daily & PR Workflows

Daily Synchronization

# Fetch and merge latest main branch changes cleanly
git pull origin main

# Check local working tree status and active branch
git status

Branching & Pull Requests

# 1. Create and switch to a new feature branch
git checkout -b feat/your-feature-name

# 2. Stage and commit changes using Conventional Commits
git add .
git commit -m "feat(api): implement settlement callback handler"

# 3. Rebase on top of latest main before opening PR
git fetch origin
git rebase origin/main

# 4. Push local branch and set upstream tracking
git push -u origin feat/your-feature-name

Conflict Reset / Hard Sync

# Discard all local branch changes and match remote main exactly
git fetch origin
git reset --hard origin/main

5. Testing & Dead Letter Queue (DLQ)

# Run Go unit test suite
make test

# Run automated End-to-End integration test suite
make test-e2e

# Inspect failed asynchronous Dead Letter Queue events
make dlq-list

# Requeue failed DLQ tasks back to PENDING state
make dlq-replay-all

# Purge generated test PDFs, XMLs, and frontend build artifacts
make clean

Financial Decimal Rule

Never use IEEE-754 floating-point numbers (float64 / float) for monetary operations. Enforce shopspring/decimal in Go and Decimal in Python.