---
auto_generated: true
created: 2026-05-18
manual_updated_at: 2026-05-18
modified: 2026-05-19
name: Developer_Manual
status: active
tags:
- client/ford
- domain/devops
- tech/python
- type/sop
type: sop
---

# Ford BnP QC System Developer Manual

## Architecture Overview
The system follows a modular architecture:
1.  **Entry Points:**
    *   `qc_engine.py`: Core engine for running QC checks locally or programmatically.
    *   `ford_qc_box_hotfolder_process.py`: Production daemon that monitors Box folders, orchestrates download, processing, and upload.
2.  **Core Logic:**
    *   `qc_module.py`: Contains `run_qc_checks()` which orchestrates the loading of profiles and execution of check scripts.
    *   `utils/config.py`: Centralized configuration management, loading from `.env` files.
    *   `utils/path_resolver.py`: Handles dynamic path resolution for profiles and assets.
3.  **Checks Library (`checks/`):**
    *   Individual Python modules for each QC rule (e.g., `special_requirements_mec_bau.py`).
    *   `html_reporter.py` / `html_error_reporter.py`: Logic for generating human-readable and error-specific reports.
4.  **Configuration:**
    *   `.env.example`: Template for environment variables.
    *   `profiles/`: JSON files defining the sequence and parameters of QC checks.

## Tech Stack
*   **Language:** Python 3.8+
*   **Box SDK:** `boxsdk` for cloud storage interaction.
*   **PDF Generation:** `reportlab` (used in `generate_pdf.py` for documentation, not core QC).
*   **Logging:** `logging` module, with optional `systemd` journal integration.
*   **Configuration:** `python-dotenv` (implied by `.env.example` usage).
*   **Service Management:** `systemd` for production deployment.

## Local Setup

### 1. Clone and Install
```bash
git clone <repo_url>
cd ford_qc_system
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt
```

### 2. Environment Variables
Copy `.env.example` to `.env.dev` and configure:

```ini
FORD_QC_ENV=development
# Box Folders (Can be dummy IDs for local-only testing without Box)
BOX_SOURCE_FOLDER_ID=0
BOX_REPORT_FOLDER_ID=0
BOX_PROCESSED_FOLDER_ID=0
# Optional: Set Box credentials if testing Box integration locally
BOX_CONFIG_FILE=ford_box_config.json
# Paths (relative to script dir)
DOWNLOAD_PATH=download_tmp
WORKING_DIR=working
QC_PROFILE_PATH=profiles/ford_bnp.json
```

### 3. Box JWT Config
Place a valid `ford_box_config.json` (from IT or Box Admin) in the project root if testing Box integration.

## Environment Variables Reference
| Variable | Description | Default/Example |
| :--- | :--- | :--- |
| `FORD_QC_ENV` | Environment mode | `production` or `development` |
| `BOX_SOURCE_FOLDER_ID` | Box folder ID for incoming assets | `332861865120` |
| `BOX_REPORT_FOLDER_ID` | Box folder ID for QC reports | `332864939558` |
| `BOX_PROCESSED_FOLDER_ID` | Box folder ID for processed assets | `332861653811` |
| `BOX_CONFIG_FILE` | Path to Box JWT JSON config | `ford_box_config.json` |
| `DOWNLOAD_PATH` | Local dir for downloads | `download_tmp` |
| `WORKING_DIR` | Local dir for extraction | `working` |
| `QC_PROFILE_PATH` | Path to QC checks definition | `profiles/ford_bnp.json` |
| `BOX_CONNECTION_TIMEOUT` | Box API connect timeout | (see code) |
| `BOX_READ_TIMEOUT` | Box API read timeout | (see code) |
| `MAX_RETRIES` | Max Box API retry attempts | (see code) |
| `WATCHDOG_INTERVAL` | Time between Box folder polls | (see code) |

## Key Services & Entry Points

### `run_qc_checks(profile_path, input_file)`
*   **Location:** `qc_module.py`
*   **Description:** The core function. Loads the QC profile (list of check definitions), iterates through them, and calls the respective check scripts. It aggregates results into a JSON structure.
*   **Inputs:** 
    *   `profile_path`: Path to JSON file.
    *   `input_file`: Path to the `.zip` asset pack.
*   **Output:** JSON string containing aggregated results.

### `run_qc_profile(profile_path, input_file)`
*   **Location:** `qc_engine.py`
*   **Description:** High-level API for running the profile. Handles JSON loading validation and result aggregation. Used by command-line interface.

### `ford_qc_box_hotfolder_process.py`
*   **Description:** The main production loop.
    1.  Authenticates with Box.
    2.  Polls `BOX_SOURCE_FOLDER_ID` every `WATCHDOG_INTERVAL` seconds.
    3.  Downloads new `.zip` files to `DOWNLOAD_PATH`.
    4.  Calls `run_qc_checks` via `qc_module`.
    5.  Generates HTML/JSON reports.
    6.  Uploads reports to `BOX_REPORT_FOLDER_ID`.
    7.  Moves processed `.zip` to `BOX_PROCESSED_FOLDER_ID`.
    8.  Handles errors via `HTMLErrorReporter`.

### `HTMLReporter` and `HTMLErrorReporter`
*   **Location:** `checks/html_reporter.py` / `checks/html_error_reporter.py`
*   **Description:** Utility classes/functions to format JSON results into Bootstrap-styled HTML. `HTMLErrorReporter` handles specific error types (network, file access, QC failure).

## API Reference (Internal)

### QC Profile JSON Structure (`profiles/ford_bnp.json`)
```json
[
  {
    "script": "checks.special_requirements_mec_bau",
    "config": {
      "some_param": "value"
    }
  },
  ...
]
```
*   `script`: Module path to the check function (e.g., `checks.module_name.check_function`).
*   `config`: Dict of parameters passed to the check.

### Result JSON Structure
```json
{
  "profile": "ford_bnp.json",
  "timestamp": "2023-10-27T10:00:00Z",
  "checks": [
    {
      "script": "checks.special_requirements_mec_bau",
      "result": {
        "status": "pass",
        "details": { "pack_type": "MEC" }
      }
    }
  ]
}
```

## Deployment

### Production (Systemd)
1.  Copy `ford_qc_box_hotfolder_process.py` to `/opt/ford_qc/bin/`.
2.  Create service file `/etc/systemd/system/ford_qc.service`:
    ```ini
    [Unit]
    Description=Ford BnP QC Box Hotfolder Processor
    After=network.target

    [Service]
    Type=simple
    User=box-cli
    Group=box-cli
    WorkingDirectory=/opt/ford_qc
    EnvironmentFile=/opt/ford_qc/.env.prod
    ExecStart=/usr/bin/python3 /opt/ford_qc/bin/ford_qc_box_hotfolder_process.py
    Restart=on-failure
    # Enable systemd journal logging
    StandardOutput=journal
    StandardError=journal

    [Install]
    WantedBy=multi-user.target
    ```
3.  Enable and start:
    ```bash
    sudo systemctl daemon-reload
    sudo systemctl enable ford_qc.service
    sudo systemctl start ford_qc.service
    ```

## Known Gotchas
1.  **Path Resolution:** The script uses `os.path.dirname(os.path.abspath(__file__))` to determine the base directory. Hardcoded paths in `qc_engine.py` (fallback) can cause issues if deployed to a different location. Always rely on `config` or relative paths.
2.  **Box Authentication:** JWT keys expire. Ensure the Box JWT key file is rotated regularly. The `BOX_CONFIG_FILE` must be up-to-date.
3.  **File Locking:** The system assumes no other process is modifying files in `WORKING_DIR`. It uses basic `os.makedirs` checks but lacks advanced file locking. Ensure exclusive access.
4.  **Memory Usage:** Large asset packs can consume significant RAM during extraction. The `FALLBACK_WORKING_DIR` is a safety net if the primary working directory lacks space.
5.  **Test Script Specifics:** `test_mec_bau_determination.py` is a debugging helper. Do not run in production. It assumes specific example files exist in `example packs/`.
6.  **PDF Generation:** `generate_pdf.py` is for documentation only and has dependencies (`reportlab`, `PIL`, `mmdc`/`mermaid-cli`) not required for the core QC system.

## Related
- [[01 Projects/ford_qc/USER_MANUAL]]
- [[ford_qc_system_box_integration]]
- [[01 Projects/ford_qc/USER_MANUAL.md]]