Quick Start¶

Project structure¶

packytrace/
├── client/
│   ├── web-app/                 # SvelteKit consumer frontend
│   └── brand-app/               # SvelteKit brand dashboard
├── contracts/                   # cross-service event contracts
├── deployment/                  # Docker Compose and infrastructure setup
├── docs/                        # living documentation source
├── packages/                    # domain-free shared SDK/infrastructure libraries
├── services/                    # eight independently deployed services
├── simulators/                  # local producer API simulators
├── go.work                      # Go workspace and required Go version
├── Makefile                     # development command entry point
├── mkdocs.yml                   # documentation configuration
└── requirements-docs.txt        # documentation dependencies

Available commands¶

make help

Common commands:

make web         # Run the frontend development server
make docs        # Run the documentation development server
make up          # Start the full stack and follow its logs
make seed        # Publish demo brand-analytics data (see below)
make health      # Show container health once
make logs        # Follow container logs
make check       # Run the fast local guardrails
make journey     # Verify the complete container stack
make ci          # Run the complete CI suite locally
make clean       # Remove selected web and documentation build output

make up waits until every container is healthy, then follows their logs. Pressing Ctrl+C stops following but leaves the containers running; use make down to stop them. Prefer make up-detached to start without attaching. Commands install their dependencies when necessary.

Seed demo analytics¶

The brand dashboard is empty until consumers have scanned products, so there is nothing to evaluate on a fresh stack. make seed publishes synthetic ProductScanned / VerdictComputed facts for the four demo brands through the Measurement Pipeline: they are aggregated by the Measurement and Brand Analytics services with a minimum group size of 5. The local 30-second demonstration window differs from the service's seven-day default and must not be described as production-equivalent configuration.

make up-detached   # stack must be running
make seed          # publish the demo facts

Wait ~15 seconds (one flush cycle) then log in to the brand app as owner@granrolo.example (or owner@muttini.example, owner@de-cello.example, owner@fabbrino.example) to see the populated charts. One product remains below the group-size threshold to show the wall dropping it.

Seeding is not repeatable against a running stack: once a window is published the pipeline will not re-emit it. There is currently no supported targeted reset for only the demonstration measurement windows; adding one is a tooling gap. Do not delete database rows manually.

!!! danger make up-build removes the complete local Compose stack, including volumes and the local database. Use it only when all local state is disposable. After confirming that, run make up-build followed by make seed to rebuild the demonstration data.

For the deployed environment the equivalent is make aws-seed (see AWS Application).