CLI Commands Reference¶

Quick reference for all command-line commands in the Smartsapp project.

All Gradle commands assume you're in backend/. If running from the repo root, prefix with -p backend.

Quick start¶

# One-time setup: enable git hooks
git config core.hooksPath .githooks

# Start local infrastructure (Postgres, Kafka, Redis)
podman-compose up postgres kafka redis redpanda-console

# Run the app (in another terminal). --continuous keeps Gradle watching
# your sources so DevTools can hot-reload when .class files change.
APP_SEED_DATA=true ./gradlew bootRun --continuous

# Run tests
./gradlew test

Set JAVA_HOME if not already configured (macOS with Homebrew):

export JAVA_HOME=/opt/homebrew/opt/openjdk@21/libexec/openjdk.jdk/Contents/Home

Backend (Gradle)¶

Run from backend/.

Command	Description
`APP_SEED_DATA=true ./gradlew bootRun --continuous`	Start the Spring Boot app on port 8080 with seed data and DevTools hot-reload. Always use `--continuous` — without it Gradle doesn't recompile on save, so DevTools has nothing to pick up and the running JVM silently drifts from your source tree.
`./gradlew bootRun`	Same as above but without seed data and without hot-reload. Only use when you deliberately want a one-shot run against existing DB state.
`./gradlew test`	Run tests with Testcontainers (requires Podman/Docker); enforces 85% JaCoCo coverage
`./gradlew build`	Full build: compile + test + coverage verification
`./gradlew bootJar`	Build executable JAR (`build/libs/system-0.0.1-SNAPSHOT.jar`)
`./gradlew clean`	Delete the build directory
`./gradlew tasks`	List all available Gradle tasks

Documentation generation¶

Command	Description
`./gradlew generateC4Docs`	Generate C4 architecture docs for all modules
`./gradlew generateC4Docs -Pmodule=canteen`	Generate C4 docs for a specific module
`./gradlew generateSystemErd`	Generate system-wide ERD to `docs/system-erd.md`

Coverage reports¶

Command	Description
`./gradlew jacocoTestReport`	Generate HTML + XML coverage reports
`./gradlew jacocoTestCoverageVerification`	Verify coverage meets 85% minimum

Reports are written to build/reports/jacoco/test/html/index.html.

Local infrastructure (Podman Compose)¶

Run from the repo root.

Command	Description
`podman-compose up postgres kafka redis redpanda-console`	Start infrastructure only (for backend developers with JDK)
`podman-compose up --build`	Start full stack including the app container
`podman-compose up -d --build`	Start full stack in background
`podman-compose down`	Stop all services

Service ports¶

Service	Port	Credentials / URL
PostgreSQL	5432	db=`system`, user=`system`, password=`system`
Kafka (Redpanda)	19092	—
Redis	6379	—
Redpanda Console	8085	`http://localhost:8085`
System app	8080	`http://localhost:8080` (only with `--build`)
Docs site	8000	`http://localhost:8000`

Git hooks¶

Hooks live in .githooks/ and are activated with:

git config core.hooksPath .githooks

Tip: Always run git commit (and other git commands) from the command line, not from your IDE's built-in Git UI. IDE integrations often swallow hook output, making it hard to see why a commit was rejected (e.g., test failures or invalid commit message format).

pre-commit¶

Runs automatically when backend/ files are staged:

If entity files changed (**/entities/*.java): regenerates docs/system-erd.md and auto-stages it
Runs ./gradlew test --quiet (aborts the commit if tests fail)
Auto-stages any specs or ERD files the test run regenerated (ui-clients/sdk/specs/, docs/system-erd.md)
If controller files changed (**/controllers/*.java): regenerates TypeScript SDK and SDK reference docs, then auto-stages them

commit-msg¶

Validates commit messages against Conventional Commits format:

type(scope): description

Allowed types: feat, fix, docs, style, refactor, test, chore, perf, ci, build, revert
Scope: optional (e.g., school, canteen)
Description: 1-72 characters

See COMMIT_CONVENTION.md for full details.

Hotfix (emergency)¶

Skip local tests and CI tests for a critical production fix. See CICD.md § Hotfix Protocol.

# Commit with --no-verify to skip pre-commit hook, [hotfix] to skip CI tests
git commit --no-verify -m "fix(module): description [hotfix]"

# Find all past hotfix commits
git log --grep='\[hotfix\]'

Container build¶

Build manually from backend/:

podman build -t smartsapp-system:latest -f Containerfile .

Uses a multi-stage build: Gradle 8.12 + JDK 21 (build) -> Eclipse Temurin 21 JRE (run), with CDS (Class Data Sharing) for faster startup.

Deployment¶

See deployment.md for the full guide. Key commands:

Terraform (infrastructure provisioning)¶

cd infrastructure/cloud_environment_setup/digitalocean/terraform
terraform init
terraform plan
terraform apply

Kubernetes¶

# Connect to cluster
doctl kubernetes cluster kubeconfig save <cluster-name>
kubectl get nodes

# Deploy
kubectl set image deployment/system-app system=<image> -n smartsapp-dev
kubectl rollout status deployment/system-app -n smartsapp-dev --timeout=300s

# Debug
kubectl logs -f deployment/system-app -n smartsapp-dev
kubectl port-forward svc/system-app 8080:80 -n smartsapp-dev

Developer portal (Backstage)¶

Run from infrastructure/operational_utilities/developer_tools/documentation-portal/.

Command	Description
`yarn start`	Start development server
`yarn build:all`	Build all packages and frontend
`yarn build:backend`	Build backend workspace
`yarn build-image`	Build container image for backend
`yarn test`	Run tests
`yarn test:all`	Run tests with coverage
`yarn test:e2e`	Run Playwright e2e tests
`yarn lint`	Lint changes since origin/master
`yarn lint:all`	Lint all files
`yarn prettier:check`	Check code formatting
`yarn new`	Create new Backstage component

The developer portal runs in staging/production only, not in the local dev stack.

Smoke tests (Newman)¶

Run from the repo root.

Command	Description
`npx newman run e2e/postman/smoke-tests.json --env-var "BASE_URL=http://localhost:8080"`	Run smoke tests against local app
`npx newman run e2e/postman/smoke-tests.json --env-var "BASE_URL=http://178.62.48.21:30080"`	Run smoke tests against dev environment

The collection can also be imported into the Postman app for interactive use.

Documentation site (MkDocs)¶

Run from the repo root.

Command	Description
`python3 scripts/generate-mkdocs-nav.py`	Regenerate `mkdocs.yml` nav from `docs/` directory (also runs automatically in pre-commit hook and CI)
`podman-compose up docs`	Start docs site via container at `http://localhost:8000` (no Python needed)
`mkdocs serve`	Start locally (requires `pip install -r requirements.txt`)
`mkdocs build`	Build static site to `site/`