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

Do not use main as the default development branch.

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/media/templates/: PDF HTML templates

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