goodgrief/README.md

Good Grief

TypeScript-first monorepo for a live theatrical photo-submission and media-control system.

Workspace

• apps/submission: mobile-first audience submission flow.
• apps/admin: operator and moderation console.
• packages/shared-types: shared domain entities and scene/cue data.
• packages/effects: reusable effect vocabulary and presets.
• packages/cue-engine: deterministic cue and transition helpers.
• packages/render-engine: scene registry and render host contracts.
• services/api: local-first Fastify API for submissions, moderation, and cueing.
• services/worker: derivative generation and retention worker.

Current status

This repository implements the MVP foundation from the planning package:

• shared TypeScript domain model
• a live-intake submission UI
• an operator-facing moderation and cue-control UI
• a local-first API/storage architecture scaffold
• scene, effect, and cue contracts for the rendering layer

Bootstrapping

1. Install dependencies with npm install.
2. Start everything together:
   • npm run dev:all
3. Or reset local runtime state first and then start everything:
   • npm run dev:all:reset

This starts:

• submission UI at http://localhost:4100
• admin UI at http://localhost:4200
• API at http://localhost:4300
• worker health at http://localhost:4301/health

Individual services

• npm run dev:api
• npm run dev:worker
• npm run dev:submission
• npm run dev:admin
• npm run reset:runtime

Both apps expect the API on http://localhost:4300 by default. Vite dev servers proxy /api and /uploads there.

Local testing notes

• Place curated images in assets/import-library/ and use the admin Rescan library folder action, or restart the API, to import them.
• The submission flow writes new uploads into storage/runtime/.
• The API state lives in data/runtime/state.json.
• Use the admin UI to approve or reject new uploads and take cues live to program.

Containers

Base compose file contains the shared backend services. Add the prod override for the built frontends:

• Podman: podman compose -f docker-compose.yml -f docker-compose.prod.yml up --build
• Docker: docker compose -f docker-compose.yml -f docker-compose.prod.yml up -d --build

That starts:

• submission UI at http://localhost:4100
• admin UI at http://localhost:4200
• API at http://localhost:4300
• worker health at http://localhost:4301/health

For local frontend hot reload, add the dev override:

• Podman: podman compose -f docker-compose.yml -f docker-compose.dev.yml up --build
• Docker: docker compose -f docker-compose.yml -f docker-compose.dev.yml up --build

To reset runtime state inside the container stack:

• Podman: podman compose -f docker-compose.yml run --rm api npm run reset:runtime
• Docker: docker compose -f docker-compose.yml run --rm api npm run reset:runtime