From 48afccbca3fa573b26c9c184dd7bf9152d2f9526 Mon Sep 17 00:00:00 2001 From: Md Bayazid Bostame Date: Sun, 29 Mar 2026 01:26:20 +0100 Subject: [PATCH] docs: expand engineering handbook and contributor guide --- CONTRIBUTING.md | 119 ++++++++++++++++++ .../workflows/developer_handbook.html | 103 ++++++++++++--- .../templates/workflows/handbook.html | 3 +- 3 files changed, 204 insertions(+), 21 deletions(-) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..6f6fce1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,119 @@ +# 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: + +```bash +./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: + +```bash +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 diff --git a/backend/workflows/templates/workflows/developer_handbook.html b/backend/workflows/templates/workflows/developer_handbook.html index 04d5474..01b9dea 100644 --- a/backend/workflows/templates/workflows/developer_handbook.html +++ b/backend/workflows/templates/workflows/developer_handbook.html @@ -23,9 +23,11 @@
Overview Structure + Workflow Local Dev Docker Database + Guidelines Translations PDF Pipeline Email Pipeline @@ -47,6 +49,7 @@
  • Repository: workdock-platform (current local path; legacy compose project name may still be retained for runtime continuity)
  • Main stack: Django + Celery + PostgreSQL + Redis + MailHog
  • Runtime mode: Docker Compose for local development and staging-style operation
    • +
  • Repository-level quick-start guide for future coders: CONTRIBUTING.md
    • @@ -54,6 +57,9 @@ -

    3) Local Development Workflow

    +

    3) Working Model

    +
    +

    Branch strategy

    + +
    +
    +

    Normal change flow

    +
      +
    1. start from develop
      2. +
    2. implement the change
      3. +
    3. run validation
      4. +
    4. update docs if architecture or workflow changed
      5. +
    5. push to GitHub and let CI run
      6. +
    6. deploy from the Mac if test-server verification is needed
      7. +
    7. promote develop into main when stable
      8. +
    +
    + +

    4) Local Development Workflow

    Start

    cd /path/to/workdock-platform
 docker compose up -d --build
    @@ -81,7 +109,7 @@ docker compose up -d --build
  • User: user_test / user12345
    • -

    4) Docker Operations

    +

    5) Docker Operations

    docker compose up -d --build
 docker compose restart web
 docker compose restart worker
@@ -93,7 +121,7 @@ docker compose down -v
    The source code is bind-mounted into the container. Most template/view/static changes only require a web restart, not a full rebuild. Image changes such as system packages require docker compose up -d --build. -

    5) Database and Migrations

    +

    6) Database and Migrations

    docker compose exec -T web python manage.py makemigrations
 docker compose exec -T web python manage.py migrate
 docker compose exec -T web python manage.py check
    @@ -101,6 +129,7 @@ docker compose exec -T web python manage.py check
  • Never edit or remove historical migrations casually.
  • When adding fields to builder-driven models, preserve fallback behavior for existing rows.
  • Fresh boot sequence runs migrations automatically in entrypoint-web.sh.
    • +
  • Do not assume database-backed admin config matches between local and deployed environments.

    • Role and Permission Model

    @@ -117,7 +146,27 @@ docker compose exec -T web python manage.py check
  • When adding a new operational page or action, define the capability in roles.py, gate the view, and hide the UI affordance when the capability is absent.
    • -

    6) Translation Workflow

    +

    7) Engineering Guidelines

    +
    +

    Core rules

    +
      +
    1. Preserve behavior while refactoring.
      2. +
    2. Prefer shared components over page-local special cases.
      3. +
    3. Do not overwrite environment-specific runtime config as a side effect of code deploys.
      4. +
    4. Keep code-driven behavior and data-driven behavior mentally separate.
      5. +
    5. Update documentation in the same branch when operational workflow changes.
      6. +
    +
    +
    +

    Code vs data

    + +
    + +

    8) Translation Workflow

    Standard Django i18n path

    make i18n-update-en
 make i18n-compile
    @@ -134,11 +183,12 @@ docker compose exec -T web django-admin compilemessages
  • preferred_language is normalized in model save() and also has a DB default of de, so alternate creation paths cannot insert null values.
    • -

    7) PDF Pipeline

    +

    9) PDF Pipeline

    -

    12) Backup and Restore

    +

    15) Backup and Restore

    make backup-create
 make backup-verify BACKUP_DIR=backups/backup_YYYYmmdd_HHMMSS
    -

    13) Host and Domain Configuration

    +

    16) Host and Domain Configuration