Development

Local Development Setup

Prerequisites

Option A: Full Stack via Docker Compose

The fastest way to get everything running:

make dev

This starts ClickHouse, all 4 Go binaries, and the Angular UI. Open http://localhost:8090.

Option B: Hot Reload (Backend + UI separately)

For iterating on code changes without rebuilding Docker images:

# Terminal 1: ClickHouse only
make ch-only
make ch-migrate     # First time only

# Terminal 2: API Gateway (restarts on save via go run)
make api

# Terminal 3: Ingestion Watcher (runs once)
make ingest

# Terminal 4: Parsing Worker
make worker

# Terminal 5: Angular dev server (hot reload, proxies /api/* to localhost:8080)
make ui-dev

Open http://localhost:4200 for the Angular dev server.

Configuration

Copy .env.example to .env and adjust as needed. Key variables for development:

Code Style

Go Backend

• Standard idiomatic Go. Handle errors explicitly; never swallow them.
• HTTP routing: Go 1.22+ stdlib net/http with method-pattern registration (e.g., mux.HandleFunc("GET /api/v1/sboms", ...)). No web framework.
• Minimal dependencies: Only 4 direct dependencies (clickhouse-go/v2, goccy/go-json, google/uuid, minio/minio-go/v7).
• JSON parsing: Use goccy/go-json for all SPDX document parsing (performance-critical).
• OSV integration: Use batch endpoints (/v1/querybatch). Shared logic in internal/osvutil.
• License logic: All categorization in internal/license with externalized policy files.

Angular Frontend

• Strict TypeScript mode and standalone components.
• OnPush change detection for data-heavy components.
• Virtual scrolling (@angular/cdk ScrollingModule) for large lists.
• Vitest for unit tests (not Karma/Jasmine).
• Never use bypassSecurityTrustHtml — use sanitizer.sanitize(SecurityContext.HTML, ...).

Example SBOM Files

The sboms/ directory includes several example files for testing. See FAQ: What example files are included? for a full description of each file.

Useful Commands