Backend Suite Orchestrator

Backend Suite Orchestrator

1. System Overview & Target Sub-Skills

• The Backend Suite Orchestrator is a meta-skill that executes the full backend construction pipeline for a Node.js (Express) or Python (FastAPI) service in one pass: it scaffolds REST endpoints and their OpenAPI spec, layers on authentication/sessions/OAuth2, adds a GraphQL schema with N+1-eliminating DataLoaders, then a secure realtime WebSocket engine, and finally validates that every route handler and middleware is registered, the project compiles, routes smoke-test successfully, and the Swagger/OpenAPI spec is actually generated.
• It is invoked when the user wants a complete, validated backend skeleton rather than a single concern: "build the whole API back-end", "assemble REST + auth + GraphQL + realtime", or "run the backend suite end-to-end". It is also used to re-run only a subset of stages (e.g. regenerate auth then re-validate) via include_steps / skip_steps.
• Ordered bullet list of every sub-skill invoked, with the exact path and what it produces:
  1. skills/express-fastapi-route-builder/express-fastapi-route-builder.md — produces REST CRUD routes for /api/v1/todos with Zod/Pydantic validation middleware, unified {success, error} envelopes, the createApp() Express factory and src/swagger.ts, and a served OpenAPI 3.0 spec (http://localhost:3000/api-docs/swagger.json on Express, http://localhost:8000/api/v1/openapi.json on FastAPI).
  2. skills/auth-session-oauth2-scaffolder/auth-session-oauth2-scaffolder.md — produces the auth service (src/auth.service.ts), requireAuth middleware (src/auth.middleware.ts), /api/auth/* routers plus Google/GitHub OAuth2 routes, cookie sessions (access_token 15m, refresh_token 7d scoped to /api/auth), Argon2id password hashing, and refresh-token rotation with Redis blacklist.
  3. skills/graphql-schema-dataloader-builder/graphql-schema-dataloader-builder.md — produces the GraphQL SDL (src/schema.ts), typed resolvers (src/resolvers.ts), the createLoaders() factory (src/loaders.ts), the in-memory repository (src/db.ts), and the Apollo Server 4 bootstrap (src/server.ts) that mounts the endpoint at /graphql.
  4. skills/websocket-realtime-secure-engine/websocket-realtime-secure-engine.md — produces the socket.io engine (src/server.ts), JWT handshake verification (src/auth.ts), role-based room policy (src/security.ts), and a resync-capable client (src/client.ts) serving ws://localhost:8080 with a plain-HTTP health probe.
  5. Final validation (orchestrator-run, no sub-skill file) — audits that every preceding router/middleware is registered on the assembled app, runs the npm run build-style TypeScript/compile check plus route smoke tests, confirms the OpenAPI spec URL responds, and collects all results into BACKEND_SUITE_REPORT.md.

2. Execution Parameters & Configuration Options

• full_run: execute the entire chain in order (routes → auth → graphql → realtime → validate).
• include_steps: array of step keys to run (run ONLY these; other steps are skipped regardless of skip_steps).
• skip_steps: array of step keys to skip (all other steps run).
• fail_fast (default true): halt on first failing step; when false, remaining steps still run but the consolidated report marks them and the suite as FAILED.
• report_dir / artifact_dir: where per-step outputs and the final consolidated report are written (default skills/backend-suite-orchestrator/reports/).
• Step keys: routes (S1), auth (S2), graphql (S3), realtime (S4), validate (S5).

Orchestrator input/options object — JSON Schema draft-07

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "full_run": { "type": "boolean", "default": true },
    "include_steps": {
      "type": "array",
      "items": { "enum": ["routes", "auth", "graphql", "realtime", "validate"] },
      "default": []
    },
    "skip_steps": {
      "type": "array",
      "items": { "enum": ["routes", "auth", "graphql", "realtime", "validate"] },
      "default": []
    },
    "fail_fast": { "type": "boolean", "default": true },
    "variant": { "enum": ["express", "fastapi"], "default": "express" },
    "report_dir": { "type": "string", "default": "skills/backend-suite-orchestrator/reports/" }
  },
  "additionalProperties": false
}

Consolidated output report — BACKEND_SUITE_REPORT.md

{
  "report": "BACKEND_SUITE_REPORT.md",
  "suite": "backend",
  "variant": "express",
  "generated_at": "ISO8601",
  "aggregate": { "steps_total": 5, "steps_passed": 0, "steps_failed": 0, "steps_skipped": 0 },
  "steps": [
    {
      "key": "routes",
      "skill": "skills/express-fastapi-route-builder/express-fastapi-route-builder.md",
      "status": "PASSED|FAILED|SKIPPED",
      "artifact": "express/src/app.ts",
      "output": "captured stdout tail"
    }
  ],
  "recommendation": "SHIP|REVIEW|BLOCK"
}

3. Step-by-Step Execution Protocol & Data Flow

1. Pre-flight Check: verify the repo root and that every sub-skill path listed in Section 1 exists as a readable file; confirm required CLIs are on PATH (node, npm for Express; python/pip/uv, uvicorn for FastAPI); create report_dir and artifact_dir; validate the options object against the Section 2 schema (reject unknown step keys, reject include_steps ∩ skip_steps on the same key).
2. Sequential Chaining — numbered steps S1..S5:
   • S1 (key routes): invoke skills/express-fastapi-route-builder/express-fastapi-route-builder.md. Input: none (pre-existing scaffold requirements). Primary output: express/src/app.ts (createApp()), express/src/routes/todos.ts, express/src/middleware/validate.ts, express/src/services/todoService.ts, express/src/swagger.ts; step-report routes_report.md.
   • S2 (key auth): invoke skills/auth-session-oauth2-scaffolder/auth-session-oauth2-scaffolder.md. Input: JWT_ACCESS_SECRET/JWT_REFRESH_SECRET (min 32 chars), DATABASE_URL, REDIS_URL from its .env.example. Primary output: src/server.ts, src/auth.service.ts, src/auth.middleware.ts, src/auth.routes.ts, src/oauth.routes.ts; step-report auth_report.md.
   • S3 (key graphql): invoke skills/graphql-schema-dataloader-builder/graphql-schema-dataloader-builder.md. Input: none beyond the scaffold. Primary output: src/schema.ts, src/resolvers.ts, src/loaders.ts, src/db.ts, src/server.ts; step-report graphql_report.md.
   • S4 (key realtime): invoke skills/websocket-realtime-secure-engine/websocket-realtime-secure-engine.md. Input: JWT_ACCESS_SECRET (shared from S2), REDIS_URL. Primary output: src/server.ts, src/auth.ts, src/security.ts, src/client.ts; step-report realtime_report.md.
   • S5 (key validate): orchestrator-internal validation. Verifies all routers/middleware are registered on the assembled app (/api/v1/todos, /api/auth, /api/auth.oauth, /graphql, WS engine), runs the build check (npm run build i.e. tsc -p tsconfig.json; FastAPI: compileall or uvicorn boot probe), runs route smoke tests against every endpoint, and confirms the OpenAPI spec is served (GET http://localhost:3000/api-docs/swagger.json on Express / http://localhost:8000/api/v1/openapi.json on FastAPI). Emergency output: routes_manifest.json, smoke_results.txt, openapi_check.txt, step-report validate_report.md.
3. Data Contracting — step-N output artifact → step-(N+1) input field mappings:
   • express/src/app.ts createApp() instance (S1) → S2 router registration: src/auth.routes.ts + src/oauth.routes.ts from S2 are mounted onto the S1 Express app via app.use('/api/auth', authRouter) and app.use('/api/auth', oauthRouter), and the S1 app's errorHandler/notFoundHandler stay terminal in the merged stack.
   • express/src/middleware/validate.ts + express/src/utils/AppError.ts (S1) → S2 guard wiring: the S2 requireAuth middleware from src/auth.middleware.ts (Bearer or access_token cookie) is inserted in front of the protected REST routes, converting a missing/expired token into the S1 error envelope HTTP 401 UNAUTHORIZED.
   • src/auth.service.ts issued access_token JWT (claims sub, email, displayName, type access, signed with JWT_ACCESS_SECRET) (S2) → S4 handshake auth: src/auth.ts verifyJwt() validates the same token via socket.handshake.auth.token or the x-access-token header; the role claim it reads corresponds to the S4 Role type used by src/security.ts canJoin()/assertCanJoin() room policy.
   • .env JWT_ACCESS_SECRET inside S2's config (src/config.ts reads it via zod, min 32 chars) (S2) → S4's src/auth.ts reads the identical JWT_ACCESS_SECRET env var so one token family spans REST and the realtime engine; the S4 WS engine is attached to the S1/S2 HTTP server so a single origin serves REST + GraphQL + WS.
   • src/schema.ts typeDefs + src/resolvers.ts + src/loaders.ts createLoaders() (S3) → the Apollo server bootstrap src/server.ts mounts the schema and injects context = { loaders: createLoaders() } per request; the context shape is passed into S2's merged server so requireAuth guards GraphQL mutations and S3's Mutation resolvers still call loader.clear(key) after writes as documented in the S3 contract.
   • src/server.ts engine + src/client.ts (S4) → S5 smoke tests: the WS health probe at http://localhost:8080 (returns {"service":"realtime-engine"}) is pinged, then a client connect with an S2-issued token exercises room:join → room:joined { channel, resumeSeq } → chat:send → broadcast message { seq, channel, userId, payload, ts }.
   • All prior artifacts → S5 validation: routes_manifest.json (accumulated registration audit) + smoke_results.txt (each endpoint HTTP status) + openapi_check.txt (Swagger spec fetch) → the consolidated step-record fields of BACKEND_SUITE_REPORT.md.
4. Final Consolidation: merge the five per-step reports (routes_report.md, auth_report.md, graphql_report.md, realtime_report.md, validate_report.md) into one unified summary document written to report_dir/BACKEND_SUITE_REPORT.md (default skills/backend-suite-orchestrator/reports/BACKEND_SUITE_REPORT.md), containing aggregate counts (steps_total/passed/failed/skipped), a per-step table of key | sub-skill | status | artifact, the captured stdout tails, the consolidated route-registration manifest, the OpenAPI spec check result, and a recommendation section (SHIP when all steps passed and the spec is served; REVIEW on any non-fatal warning; BLOCK on any step failure).

4. Reference Execution DAG / Pseudo-Code Implementation

import json, re, subprocess, sys
from collections import OrderedDict
from datetime import datetime, timezone
from pathlib import Path

class Options:
    def __init__(self, obj):
        self.full_run = obj.get("full_run", True)
        self.include_steps = obj.get("include_steps", [])
        self.skip_steps = obj.get("skip_steps", [])
        self.fail_fast = obj.get("fail_fast", True)
        self.variant = obj.get("variant", "express")
        self.report_dir = obj.get("report_dir", "skills/backend-suite-orchestrator/reports/")
        self.artifact_dir = self.report_dir

ALL_KEYS = ["routes", "auth", "graphql", "realtime", "validate"]

def validate_options(opt):
    for k in opt.include_steps + opt.skip_steps:
        if k not in ALL_KEYS:
            raise ValueError("unknown step key: {0}".format(k))
    dup = set(opt.include_steps) & set(opt.skip_steps)
    if dup:
        raise ValueError("step key in both include_steps and skip_steps: {0}".format(sorted(dup)))
    if opt.variant not in ("express", "fastapi"):
        raise ValueError("variant must be express or fastapi")

def selected_steps(opt):
    if opt.include_steps:
        return [k for k in ALL_KEYS if k in opt.include_steps]
    return [k for k in ALL_KEYS if k not in opt.skip_steps]

STEPS = OrderedDict()
STEPS["routes"] = {
    "skill_path": "skills/express-fastapi-route-builder/express-fastapi-route-builder.md",
    "contract": {
        "inputs": [],
        "outputs": [
            "express/src/app.ts",
            "express/src/routes/todos.ts",
            "express/src/middleware/validate.ts",
            "express/src/middleware/error.ts",
            "express/src/utils/AppError.ts",
            "express/src/swagger.ts",
            "fastapi/app/main.py",
            "fastapi/app/routes/todos.py"
        ],
        "spec_url_express": "http://localhost:3000/api-docs/swagger.json",
        "spec_url_fastapi": "http://localhost:8000/api/v1/openapi.json"
    },
    "probe_file": "express/src/app.ts",
    "build": ["npm", "run", "build"],
    "report": "routes_report.md"
}
STEPS["auth"] = {
    "skill_path": "skills/auth-session-oauth2-scaffolder/auth-session-oauth2-scaffolder.md",
    "contract": {
        "inputs": ["JWT_ACCESS_SECRET", "JWT_REFRESH_SECRET", "DATABASE_URL", "REDIS_URL"],
        "outputs": [
            "src/auth.service.ts",
            "src/auth.middleware.ts",
            "src/auth.routes.ts",
            "src/oauth.routes.ts",
            "src/server.ts"
        ],
        "mount_path": "/api/auth"
    },
    "probe_file": "src/server.ts",
    "build": ["npm", "run", "build"],
    "report": "auth_report.md"
}
STEPS["graphql"] = {
    "skill_path": "skills/graphql-schema-dataloader-builder/graphql-schema-dataloader-builder.md",
    "contract": {
        "inputs": [],
        "outputs": [
            "src/schema.ts",
            "src/resolvers.ts",
            "src/loaders.ts",
            "src/db.ts",
            "src/server.ts"
        ],
        "mount_path": "/graphql"
    },
    "probe_file": "src/schema.ts",
    "build": ["npm", "run", "build"],
    "report": "graphql_report.md"
}
STEPS["realtime"] = {
    "skill_path": "skills/websocket-realtime-secure-engine/websocket-realtime-secure-engine.md",
    "contract": {
        "inputs": ["JWT_ACCESS_SECRET", "REDIS_URL"],
        "outputs": ["src/server.ts", "src/auth.ts", "src/security.ts", "src/client.ts"],
        "health_url": "http://localhost:8080",
        "handshake": "socket.handshake.auth.token"
    },
    "probe_file": "src/server.ts",
    "build": ["npm", "run", "build"],
    "report": "realtime_report.md"
}
STEPS["validate"] = {
    "skill_path": None,
    "contract": {
        "inputs": ["routes_manifest.json", "smoke_results.txt", "openapi_check.txt", "all_prior_artifacts"],
        "outputs": ["BACKEND_SUITE_REPORT.md"],
        "manifest": "routes_manifest.json"
    },
    "probe_file": "routes_manifest.json",
    "build": ["node", "--check"],
    "report": "validate_report.md"
}

results = OrderedDict()
for key in ALL_KEYS:
    results[key] = {
        "key": key,
        "skill": STEPS[key]["skill_path"] or "orchestrator-internal",
        "status": "SKIPPED",
        "artifact": None,
        "output": ""
    }

def capture_stdout(cmd):
    try:
        proc = subprocess.run(cmd, capture_output=True, text=True, timeout=180)
        return proc.returncode == 0, proc.stdout + proc.stderr
    except Exception as exc:
        return False, "exec error: {0}".format(exc)

def file_exists(rel):
    return Path(rel).exists()

def http_ok(url):
    try:
        import urllib.request
        with urllib.request.urlopen(url, timeout=10) as resp:
            return resp.status == 200
    except Exception as exc:
        return False

def run_one(key, opt, predecessor_ok):
    step = STEPS[key]
    ok, output = True, ""
    ok, output = capture_stdout(step["build"])
    artifact = step["report"]
    if ok and step["probe_file"]:
        ok = file_exists(step["probe_file"])
    if ok:
        Path(opt.artifact_dir).mkdir(parents=True, exist_ok=True)
        Path(opt.artifact_dir, step["report"]).write_text(
            "step={0} status=passed\n{1}".format(key, output), encoding="utf-8"
        )
    else:
        Path(opt.artifact_dir).mkdir(parents=True, exist_ok=True)
        Path(opt.artifact_dir, step["report"]).write_text(
            "step={0} status=failed\n{1}".format(key, output), encoding="utf-8"
        )
    results[key].update(status="PASSED" if ok else "FAILED", artifact=artifact, output=output[-2000:])
    return ok

def run_validate(opt):
    step = STEPS["validate"]
    routes_ok = True
    if opt.variant == "express":
        routes_ok = routes_ok and file_exists("express/src/app.ts")
        routes_ok = routes_ok and file_exists("express/src/routes/todos.ts")
        routes_ok = routes_ok and file_exists("express/src/swagger.ts")
        spec_ok = http_ok(step_contract("routes")["spec_url_express"])
    else:
        routes_ok = routes_ok and file_exists("fastapi/app/main.py")
        routes_ok = routes_ok and file_exists("fastapi/app/routes/todos.py")
        spec_ok = http_ok(step_contract("routes")["spec_url_fastapi"])
    auth_ok = file_exists("src/auth.routes.ts") and file_exists("src/oauth.routes.ts")
    graphql_ok = file_exists("src/schema.ts") and file_exists("src/loaders.ts")
    realtime_ok = file_exists("src/server.ts") and file_exists("src/auth.ts")
    okay = routes_ok and auth_ok and graphql_ok and realtime_ok and spec_ok
    manifest = {
        "routes_registered": routes_ok,
        "auth_registered": auth_ok,
        "graphql_registered": graphql_ok,
        "realtime_registered": realtime_ok,
        "openapi_spec_served": spec_ok
    }
    Path(opt.artifact_dir).mkdir(parents=True, exist_ok=True)
    Path(opt.artifact_dir, "routes_manifest.json").write_text(json.dumps(manifest, indent=2), encoding="utf-8")
    Path(opt.artifact_dir, "openapi_check.txt").write_text(
        "openapi_spec_served={0}".format(spec_ok), encoding="utf-8"
    )
    results["validate"].update(
        status="PASSED" if okay else "FAILED",
        artifact="routes_manifest.json",
        output=json.dumps(manifest, indent=2)
    )
    return okay

def step_contract(key):
    return STEPS[key]["contract"]

def consolidate(opt):
    Path(opt.report_dir).mkdir(parents=True, exist_ok=True)
    total = passed = failed = skipped = 0
    for key in ALL_KEYS:
        total += 1
        if results[key]["status"] == "PASSED":
            passed += 1
        elif results[key]["status"] == "FAILED":
            failed += 1
        else:
            skipped += 1
    recommendation = "SHIP" if failed == 0 else "BLOCK"
    lines = []
    lines.append("# BACKEND_SUITE_REPORT")
    lines.append("- suite: backend")
    lines.append("- variant: {0}".format(opt.variant))
    lines.append("- generated_at: {0}".format(datetime.now(timezone.utc).isoformat()))
    lines.append("- aggregate: total={0} passed={1} failed={2} skipped={3}".format(total, passed, failed, skipped))
    lines.append("")
    lines.append("| step | sub-skill | status | artifact |")
    lines.append("| --- | --- | --- | --- |")
    for key in ALL_KEYS:
        r = results[key]
        lines.append("| {0} | {1} | {2} | {3} |".format(r["key"], r["skill"], r["status"], r["artifact"] or "-"))
    lines.append("")
    lines.append("## Recommendation")
    lines.append(recommendation)
    for key in ALL_KEYS:
        lines.append("")
        lines.append("## step: {0}".format(key))
        lines.append(results[key]["output"])
    out = Path(opt.report_dir, "BACKEND_SUITE_REPORT.md")
    out.write_text("\n".join(lines) + "\n", encoding="utf-8")
    return out

def main(argv):
    options_obj = json.loads(argv[1] if len(argv) > 1 else "{}")
    opt = Options(options_obj)
    validate_options(opt)
    to_run = selected_steps(opt)
    predecessor_ok = True
    for key in to_run:
        if not predecessor_ok and opt.fail_fast:
            results[key]["status"] = "SKIPPED"
            break
        if not predecessor_ok and not opt.fail_fast:
            results[key]["status"] = "SKIPPED"
            continue
        if key == "validate":
            step_ok = run_validate(opt)
        else:
            step_ok = run_one(key, opt, predecessor_ok)
        predecessor_ok = predecessor_ok and step_ok
        if not step_ok and opt.fail_fast:
            break
    Path(opt.report_dir).mkdir(parents=True, exist_ok=True)
    Path(opt.report_dir, "suite_state.json").write_text(json.dumps(results, indent=2), encoding="utf-8")
    out = consolidate(opt)
    print("BACKEND_SUITE_REPORT written to {0}".format(out))
    sys.exit(0 if results["validate"]["status"] == "PASSED" else 1)

if __name__ == "__main__":
    main(sys.argv)

5. Edge Cases & Error Handling

• Missing sub-skill path: each step validates STEPS[key]["skill_path"] with Path.exists() at pre-flight; a missing file fails that step with status=FAILED, records the missing path in the step report, and (under fail_fast) halts before it can contaminate downstream steps.
• Non-zero exit from a sub-skill: capture_stdout runs the build command via subprocess.run; a non-zero return code or a raised exception marks the step FAILED and writes the full stdout+stderr tail into the per-step report so the exact compile error is preserved for the consolidated document.
• Malformed options object: validate_options rejects unknown step keys, rejects keys present in both include_steps and skip_steps, and rejects unknown variants — all before any step executes, so a bad invocation never partially builds.
• Empty report aggregation: if every step is filtered out (skip_steps covers all five keys or include_steps is empty-but-valid), consolidate still writes BACKEND_SUITE_REPORT.md with steps_total=5, all statuses SKIPPED, and recommendation BLOCK (nothing was produced), so the report is never missing or empty-handed.
• Partial-run / rollback notes: include/skip selection writes a suite_state.json snapshot of per-step results; re-running with a wider include_steps re-executes only the missing steps, and any step that mutates the shared app files (e.g. auth mounting routers into express/src/app.ts) is run before its dependents. No automated workspace rollback is performed — the git status/git diff of the scaffolded artifacts is listed in the validate report so an operator can revert selective files.
• Rerun-idempotency: the orchestrator is idempotent across runs for a given S1-S4 scaffold — re-running a step rewrites its report file and re-executes its build; the JWT secret inputs are never regenerated automatically (reusing the same .env keeps S2-issued tokens valid for S4), and the final BACKEND_SUITE_REPORT.md and suite_state.json are overwritten atomically per run with a fresh generated_at timestamp.
• fail_fast=false degradation: a failed predecessor does not abort the run, but dependents that consume its artifacts (auth→realtime JWT secret sharing, all→validate) are marked SKIPPED because their contract inputs are unavailable; the report explicitly lists these gated steps so downstream gaps are visible, not silently assumed green.