Quick Reference

Fast lookup for common commands, paths, and patterns.

Most Common Commands

Build/Regenerate a Schema

# Full pipeline (recommended) - validates, converts, generates all configs
python -m codegen.cli all container_tracking
python -m codegen.cli all shipping

# Generate all active modules for a cpm5 assembly
python -m codegen.cli all --assembly cpm5_01_fleet

# Create a new assembly (auto-assigns next sequential number)
python -m codegen.cli new-assembly cpm5 fleet --modules core,assets,workforce,maintenance

# Generate ID conversion script when re-importing a table
python -m codegen.cli convert-ids --assembly cpm5_01_fleet --table PlantDetail

Individual DSL Commands

python -m codegen.cli validate <schema>   # Validate DSL syntax
python -m codegen.cli convert <schema>    # Convert DSL to JSON/models
python -m codegen.cli menu <schema>       # Generate menu JSON
python -m codegen.cli dashboard <schema>  # Generate dashboard config
python -m codegen.cli config <schema>     # Generate app/ui config

Run Development Server

# Run individual apps
python server/run.py shipping              # Port 5015
python server/run.py container_tracking    # Port 5016

# List all configured applications
python server/run.py --list

# Run with custom config
python server/run.py shipping --config installations/client.yaml

Control Panel (Multi-App Management)

# Start control panel to manage all applications
python server/control_panel.py

# Control panel features:
# - Runs on port 5000 (http://localhost:5000)
# - Auto-starts apps with auto_start: true in applications.yaml
# - Start/stop/restart individual apps or all apps
# - View logs and monitor stats (CPU, memory, uptime, connections)
# - Automatically stops all apps on exit (Ctrl+C)

# Use instead of multiple terminal windows for running apps

Application Registry

# List configured applications
python server/run.py --list

# Run with custom config (client-specific)
python server/run.py shipping --config installations/client.yaml

# Config file location
applications.yaml                    # Main config (project root)
installations/*.yaml                 # Client-specific configs

App Branding (Logo + Title)

Logo — set per app in applications.yaml, overridable per client in installations/*.yaml:

applications:
  container_tracking:
    logo: "img/logos/argo_2.png"   # path relative to /static/

Place image files in server/static/img/logos/. Leave logo unset (or omit it) for no logo.

Title / Brand name — set in apps/{schema}/schema/app_config.yaml:

app:
  name: ""                  # optional prefix shown before title — leave empty to hide
  title: "Container Tracking"   # main title shown in header

The shared header partial (server/templates/base/includes/_header.html) renders: [☰] [name (if set)] [title] [logo (if set)] — used by index.html, list.html, and dashboard.html.

Database Operations

# Database tables are auto-created when Flask app starts

# Database locations (per app):
# apps/{app_name}/data/{app_name}.db  (configured in applications.yaml)

# Reset database (WARNING: deletes all data!)
rm apps/shipping/data/shipping.db
# Restart app to recreate

# Backup database
cp apps/shipping/data/shipping.db apps/shipping/data/shipping.db.backup

# Check tables via SQLite
sqlite3 apps/shipping/data/shipping.db ".tables"

Container Tracking — Demurrage Calculator

# One-off migration (run once per environment, idempotent):
# - Removes duplicate depot_charge_rate rows
# - Adds UNIQUE INDEX on demurrage_period(start_event_id)
python apps/container_tracking/migrate_demurrage_constraints.py

# Rebuild all demurrage periods from scratch:
python apps/container_tracking/calculate_demurrage.py --recalc

# Incremental update (new OPEN periods only, safe to run anytime):
python apps/container_tracking/calculate_demurrage.py

# Web UI recalculate button triggers incremental mode via:
# POST /demurrage/recalculate

Key rules enforced by the calculator: - CLOSE_ACTIONS: Receive Empty/Full, Load Full, Disposal, Sold, Send/Transfer Ship, Send/Transfer Return - Same-day close events ARE picked up (uses ch.id > start_id tiebreaker) - Overlapping periods for the same container are skipped with a logged warning - See: docs/sessions/2026-06-16_demurrage_calculator_analysis_and_fixes.md

View Profiles and Filtered Views

Full reference: docs/features/VIEW_PROFILES_AND_FILTERED_VIEWS.md

Rule: menu_config.yaml filter: controls which records appear. field_config.yaml profiles: controls which columns appear. Never put filters: inside a profile — it is silently overridden by URL params.

Key File Locations

DSL & Schemas

Generated Output

cpm5 Modular Assembly

Application Files

Configuration

Authentication

Enable Google auth: add client_id + client_secret under applications.<app>.auth.google_oauth in applications.yaml

Disable Google auth (fall back to PIN): blank or comment out client_id/client_secret

Bootstrap first developer user (no UI exists yet — insert directly):

import sqlite3, datetime
conn = sqlite3.connect('server/data/auth.db')
conn.execute(
    'INSERT INTO developer_users (email, name, is_active, created_at) VALUES (?,?,1,?)',
    ('your@email.com', 'Your Name', datetime.datetime.utcnow().isoformat())
)
conn.commit(); conn.close()

Databases & Logs

Scripts

Development Servers

DSL File Format

# File: apps/shipping/schema/shipping.dsl
schema: shipping

table: customer
  fields:
    id: integer, primary_key
    name: string
    email: string
  views:
    list: [id, name, email]
    form: [name, email]

table: order
  fields:
    id: integer, primary_key
    customer_id: integer, foreign_key(customer.id)
    total: decimal
  relationships:
    customer: customer

Troubleshooting Quick Fixes

"Module not found" error

# Make sure you're in project root
cd ~/Dev/simpleFlask/dsl_15_simple_node

# Check Python path
echo $PYTHONPATH

# Add to path if needed
export PYTHONPATH="${PYTHONPATH}:$(pwd)"

Database errors

# Delete and recreate database
rm apps/shipping/data/shipping.db

# Run the app - it will recreate the DB
python server/run.py shipping

Regenerate everything

# Full regeneration
python -m codegen.cli all shipping
python -m codegen.cli all container_tracking

# Restart server (or use control panel)
python server/run.py shipping

Documentation Quick Links

Quick Decision Tree

Q: I want to...

• Add/modify a schema -> Edit apps/{app}/schema/{app}.dsl, then python -m codegen.cli all {app}
• Create a new cpm5 assembly -> python -m codegen.cli new-assembly cpm5 {name} --modules core,{module list}
• Add a module to an assembly -> Uncomment the import in apps/cpm5/assemblies/{assembly}/index.dsl, then python -m codegen.cli all --assembly {assembly}
• Override hooks for an assembly -> Create apps/cpm5/assemblies/{assembly}/overrides/{module}/custom/hooks.py (replaces module hooks entirely)
• Promote an assembly change to module -> Move code from assemblies/{assembly}/overrides/{module}/custom/ into modules/{module}/custom/
• Backfill IDs after activating a module -> python -m codegen.cli convert-ids --assembly {assembly} --table {TableName}
• Change app settings -> Edit apps/{app}/schema/app_config.yaml, restart server (read directly from YAML)
• Change UI settings -> Edit apps/{app}/schema/ui_config.yaml, then python -m codegen.cli config {app}
• Change menu structure -> Edit apps/{app}/schema/menu_config.yaml, then python -m codegen.cli menu {app}
• Change dashboard -> Edit apps/{app}/schema/dashboard_config.yaml, restart server (read directly from YAML)
• Manage multiple apps -> Use python server/control_panel.py for multi-app management
• Debug a problem -> Check docs/debugging/ for similar issues
• Understand code flow -> See docs/core/ numbered guides

Last Updated: 2026-05-09