MDL Ops Engine - Workspace Developer Guide

1. Architecture Overview

This workspace uses a Meta-Repository architecture. * Parent Repo (mdl-ops-engine): Acts as the orchestrator. It tracks the infrastructure (docker-compose.yml), documentation, and pointers to the child repositories. * Child Repos (Submodules): Independent Git repositories that contain the source code: * bsc -> blind-shipping-calculator (Frontend Web App) * n8n -> n8n-intelligence-service (Workflows & Dockerfile) * qbo_intelligence_system -> (Local Python Service)

2. Daily Development Workflow

Quick Start (VS Code Tasks)

We have configured VS Code Tasks for common operations. Press F1 -> Type "Run Task": * 🚀 Start Ops Engine: Boots up the entire Docker stack. * 💻 Start BSC App: Runs the Next.js app locally on port 3100. * 🤖 Start n8n Only: Boots just the automation service.

The "Two-Step Commit" Rule

When modifying a submodule (e.g., n8n or bsc): 1. Commit Child First: Go into the folder (cd n8n), commit, and push to its own repo. 2. Update Parent: Go to root, commit the version bump ("Update n8n to latest"). * Tip: We have a pre-commit hook available in scripts/git-hooks/ to enforce this.

3. Deployment SOPs

Vercel (Blind Shipping Calculator)

• Project Name: bsc
• Strategy: Direct Repository Connection
• Do NOT connect Vercel to mdl-ops-engine.
• DO connect Vercel directly to the bsc repository.
• Reason: Keeps the private Ops Engine / n8n workflows secure and prevents build errors.

n8n (Automation Engine)

• Host: Docker Container (n8n-ops-engine)
• Data Persistence: Bound to n8n/ directory.
• Deduplication: Uses MD5 checksums.
• Backups: Workflows are automatically saved to n8n/all_workflows_formatted.json on export.

5. Container Cheat Sheet

In this environment, Docker may prepend instance IDs to container names. Use * or check docker ps first.

Tip: Always run docker ps --format "{{.Names}}" if a command fails with "No such container".