ASQ Global Monorepo

This repository hosts the asq-global platform (Ask and Schedule Quickly) under the asd-engineering organisation. It consolidates the core ASQ services, tooling, and infrastructure into a single workspace.

Structure

apps/                 # Application frontends/backends
services/             # Supporting microservices
packages/             # Shared Python/JS libraries and assets
qa/                   # Test suites (Cypress, k6)
infra/                # Deployment scripts, Docker images, database resources
docs/                 # API documentation and developer guides
qa-shared/            # Reusable QA fixtures and datasets
tools/                # Monorepo automation and CI templates
config/               # Environment templates and secret management

External Dependencies

• aioredis-py and tartiflette-aiohttp remain separate forks under the asd-engineering organisation and are consumed as git-based dependencies until suitable replacements are adopted.

Development Commands

The repository uses Just command runner with 235+ commands across 10 modules. Run just to see quick start commands, or just --list for all available commands.

Quick Start

# First-time setup (installs Python, dependencies, configs)
just dev-setup

# Start all services (Docker + backend + frontend + services)
just start-all

# Setup database with test data
just db-full-setup

# Run tests
just test-quick

Orchestration Workflows

• just dev-setup — complete first-time development environment setup
• just start-all — start entire stack (all services)
• just stop-all — stop all services
• just restart-all — restart all services
• just db-full-setup — setup database with test data
• just db-refresh — reset and reload test data
• just build-all — build all Docker images
• just ci-full — full CI simulation (linting + all tests)
• just clean-all — clean build artifacts
• just clean-nuclear — stop and clean everything

Backend

• just backend-install-python — install CPython 3.11 via helper script (requires sudo)
• just backend-install-pipenv — install Pipenv alongside the repo-local Python toolchain
• just backend-install-dbmate — install dbmate into ./local/bin (no sudo)
• just backend-setup-config — create apps/backend/config/local from example if missing
• just backend-init-local-docker — prepare local Postgres/Redis data directories (requires sudo)
• just backend-pipenv-install — install backend dependencies with Pipenv (project-local venv)
• just backend-test — execute the backend pytest suite
• just test — alias for backend-test
• just backend-lint — run linting (flake8, mypy, etc.)
• just backend-lint-fix — auto-fix linting issues
• just python, just pip, just pipenv, just dbmate — invoke repo-local binaries directly

Frontend

• just frontend-install — install frontend dependencies with npm
• just frontend-serve — start dev server (OpenAPI-to-GraphQL + Vue dev server on port 3000)
• just frontend-serve-simple — start only Vue dev server without OpenAPI-to-GraphQL
• just frontend-build — build frontend for production
• just frontend-start — start frontend in production mode with PM2
• just frontend-lint — run frontend linter
• just frontend-generate-schema — generate GraphQL schema from OpenAPI swagger.yaml
• just frontend-generate-types — generate TypeScript types from GraphQL schema
• just frontend-sync — sync submodules and regenerate schema + types (full sync)

Docker

• just docker-up-all — start full stack
• just docker-up-backend — start backend + dependencies
• just docker-up-frontend — start full web stack
• just docker-down — stop all services
• just docker-logs — follow logs from all services
• just docker-shell-backend — bash in backend container
• just docker-psql — psql in postgres container

Database

• just db-wait — wait for database to be ready
• just db-setup-pytest — setup test database schema
• just db-mock — load mock data for development
• just db-migrate — apply database migrations
• just db-rollback — rollback last migration
• just db-reset — drop and recreate database

Testing

• just test-all — run all tests (backend + frontend + services)
• just test-quick — quick tests (unit only)
• just test-backend — all backend tests
• just test-backend-unit — backend unit tests only
• just test-backend-integration — backend integration tests only
• just test-backend-coverage — run with coverage report

Services

Message Engine:

• just message-engine-build — build Docker image
• just message-engine-run — run service
• just message-engine-kill — kill running service

Psychopomp:

• just psychopomp-build — build Docker image
• just psychopomp-run — run service
• just psychopomp-stop — stop service

Locales & Git

• just locales-pull — pull translations from Phrase
• just locales-push — push translations to Phrase
• just locales-sync — sync translations (push then pull)
• just git-push-current — push current branch to origin
• just git-fixup COMMIT — create fixup commit and autosquash rebase

Help & Documentation

• just --list — list all 235+ available commands
• just backend-help — backend module help
• just docker-help — docker module help
• just orchestration-help — orchestration workflows help

See docs/just-commands.md for complete command reference organized by module.