workdock-platform/CONTRIBUTING.md

Contributing Guide

Purpose

This repository is the standalone productized Workdock platform.

Use this file as the quick-start guide for future coders. It complements:

• DEPLOYMENT.md
• backend/workflows/templates/workflows/project_wiki.html
• backend/workflows/templates/workflows/developer_handbook.html

If you change architecture, deployment flow, or operational behavior, update the relevant documentation in the same branch.

Branch Policy

• develop: active integration branch
• main: stable branch for production promotion
• short-lived feature branches: branch from develop, merge back into develop
• customer release branches: branch from main for a frozen customer line when a customer must not receive future feature work automatically

Do not use main as the default development branch.

Customer release policy

For customer-specific deliveries such as TUBCO, use a dedicated release branch from the current stable line.

Recommended pattern:

• release/tubco-v1: customer maintenance branch
• tubco-baseline-2026-03: baseline tag taken from the same stable point

Rule:

• new product features continue on develop
• customer release branches only receive approved:
  • bug fixes
  • security updates
  • UI improvements

Do not let a customer deployment track develop directly.

Current Delivery Model

• GitHub Actions is used for CI
• the current test server is local/LAN-only
• deployment to the test server is manual from a LAN-connected machine

Standard test deployment command:

./scripts/deploy_test_from_mac.sh

Why:

• GitHub-hosted runners cannot reliably reach the private LAN target at 192.168.2.55

Architecture Summary

Main stack:

• Django
• Celery
• PostgreSQL
• Redis
• Caddy

Important repository areas:

• backend/config/: Django configuration
• backend/workflows/: application code
• backend/workflows/templates/workflows/: templates and in-app documentation
• backend/workflows/static/workflows/: CSS and JS
• backend/workflows/pdf_assets/: default PDF HTML templates and default letterhead

Current backend modularization:

• views.py: thin route wrapper layer
• split view modules:
  • request_views.py
  • account_views.py
  • admin_config_views.py
  • form_builder_views.py
  • observability_views.py
  • integration_admin_views.py
  • welcome_email_views.py
  • intro_builder_views.py
• tasks.py: async task entrypoints/orchestration
• pdf_rendering.py and pdf_sections.py: PDF rendering
• email_workflows.py and notification_dispatch.py: mail/notification orchestration
• models.py: stable import facade over split model modules

Engineering Rules

1. Preserve runtime behavior while refactoring.
2. Prefer shared UI/system primitives over page-local one-off patterns.
3. Do not silently overwrite environment-specific configuration data.
4. Treat database-backed admin configuration as runtime state, not seed data.
5. Update docs when workflow or architecture changes.

Code vs Data

Not all visible behavior comes from code.

Code-driven:

• page layout
• permissions
• routing
• task behavior
• deploy scripts

Database-driven:

• app registry order and visibility
• branding and company config
• builder settings
• intro checklist items
• notification templates and rules

If local UI and server UI differ, check the database-backed config before assuming a code drift.

Testing Rules

Minimum validation after non-trivial changes:

docker compose exec -T web python manage.py check
docker compose exec -T web python manage.py test

Also verify specifically when changing:

• PDFs
• deployment/config
• templates/UI

Documentation Rules

Keep these current:

• DEPLOYMENT.md
• PRODUCTIZATION_ROADMAP.md
• backend/workflows/templates/workflows/project_wiki.html
• backend/workflows/templates/workflows/developer_handbook.html

Recommended Change Flow

1. Start from develop
2. Implement the change
3. Validate locally
4. Update docs if needed
5. Push to GitHub
6. Let CI run
7. Deploy from the Mac if runtime verification is needed
8. Promote develop to main when stable