Project Layout

This page is the canonical source of truth for repository and module layout in this project.

Repository Root

  • AGENTS.md: short mandatory instructions for agents
  • mkdocs.yml: canonical MkDocs configuration
  • docs/: canonical project documentation source
  • .sops.yaml: SOPS creation rules for encrypted env files
  • secrets/: encrypted source of truth for module env files
  • scripts/: root orchestration and shared helper scripts
  • ab-ticket-bot-jobs/: deployable worker module
  • ab-ticket-bot-docs/: deployable docs packaging module

Module Naming

  • the project slug is ab-ticket-bot
  • deployable modules are named ab-ticket-bot-jobs and ab-ticket-bot-docs
  • Docker image names, container names, compose project names, and operational scripts reuse the exact module directory name

Root Scripts

  • scripts/start.sh: starts all modules in dependency order
  • scripts/stop.sh: stops all modules in reverse order
  • scripts/deploy.sh: materializes production env files and deploys all modules
  • scripts/materialize-secret.sh: renders one module env file from secrets/
  • scripts/sops-common.sh: shared SOPS helper functions
  • scripts/remote-deploy-common.sh: shared remote tar and SSH deploy helper

Jobs Module Layout

ab-ticket-bot-jobs/ owns:

  • Dockerfile
  • docker-compose.yml
  • .env.example
  • .env.local and .env.server as materialized runtime files
  • README.md
  • ab_ticket_bot_jobs/
  • data/
  • logs/
  • conf/
  • scripts/ab-ticket-bot-jobs-common.sh
  • scripts/ab-ticket-bot-jobs-start.sh
  • scripts/ab-ticket-bot-jobs-stop.sh
  • scripts/ab-ticket-bot-jobs-deploy.sh

Docs Module Layout

ab-ticket-bot-docs/ owns:

  • Dockerfile
  • docker-compose.yml
  • .env.example
  • .env.local and .env.server as materialized runtime files
  • README.md
  • serve_docs.py
  • build-context/ as generated packaging input copied from root docs/ and mkdocs.yml
  • data/
  • logs/
  • conf/
  • scripts/ab-ticket-bot-docs-common.sh
  • scripts/ab-ticket-bot-docs-start.sh
  • scripts/ab-ticket-bot-docs-stop.sh
  • scripts/ab-ticket-bot-docs-deploy.sh

Secret Layout

  • local secrets: secrets/local/<module>.env
  • production secrets: secrets/prod/<module>.env
  • source of truth stays encrypted under secrets/
  • materialized .env.local and .env.server are runtime artifacts and must not be committed