Handbook

Engineering architecture map

One-page map of 360 Insights Studio and the underlying feedback360 pipeline. All components run locally; confidential PDFs and JSON never leave the machine unless the operator exports a zip.

Updated 2026-07-17

System layers

┌─────────────────────────────────────────────────────────────────┐
│  Electron shell (desktop/)                                       │
│  spawn/attach backend · IPC · OS file dialogs · keystore       │
└────────────────────────────┬────────────────────────────────────┘
                             │ http://127.0.0.1:8914
┌────────────────────────────▼────────────────────────────────────┐
│  Studio API (feedback360/app_server.py)                          │
│  workspaces · generate jobs · verify gate · export · PDP · AI    │
└─────┬──────────────────┬──────────────────┬─────────────────────┘
      │                  │                  │
      ▼                  ▼                  ▼
┌───────────┐    ┌──────────────┐    ┌─────────────────┐
│ Pipeline  │    │ Verification │    │ AI enrichment   │
│ parse →   │    │ verify_      │    │ providers/      │
│ analyze → │    │ extraction   │    │ enrich (memory  │
│ render    │    │ + golden     │    │ keys only)      │
└───────────┘    └──────────────┘    └─────────────────┘

Pipeline core (`feedback360/`)

Module	Role
`parse_360.py`	PDF → `data.json` (pdfplumber text + geometry)
`analyze.py`	`data.json` → `metrics.json` (deterministic formulas)
`render_html.py`	JSON → `360-report.html` + `wiki/*.html`
`export_snapshot.py`	Shared offline zip builder (export + website snapshots)
`__main__.py`	CLI: `--stage`, `--serve`, `--app`

CLI and Studio jobs share the same three stages. See pipeline.md.

HTTP servers

Mode	Port (default)	Entry	Purpose
Legacy dynamic dashboard	8913	`--serve --out <dir>`	Live weight sliders on static render
360 Insights Studio	8914	`--app`	Workspaces, jobs, verify-gated export, PDP, AI

Both bind 127.0.0.1 only. Studio contract: app-api.md; internal state machines and gates: app-logic.md.

Verification harness

Before export, Studio runs verify_extraction.run_verification() on every generate job. Three layers (arithmetic, independent PDF re-read, golden drift) are documented in pipeline.md. Export and /api/export require verify.json with "verdict": "pass".

AI layer

Optional narratives and PDP drafting call provider adapters under feedback360/ai/. API keys are stored in memory only for the server session (never on disk). Provider matrix and test flow: ai-providers.md.

Electron shell

desktop/main.js resolves Python (packaged binary or dev .venv), picks port 8914 (with attach-if-already-running), loads desktop/ui/. IPC surface and screen map: desktop.md.

Packaging

Piece	Tool	Output
Python backend	PyInstaller (`packaging/build-backend.sh`)	`feedback360-backend` binary
Desktop app	electron-builder	AppImage, deb, NSIS, dmg, portable
CI	GitHub Actions matrix	Per-OS artifacts on release tags

Details, unsigned-app notes, and local build commands: packaging.md.

Orchestration (PDCA)

Phased build loop under orchestration/ (read-only prompts and checks):

Phases 10–160 — parse, analyze, render, verification, Studio, desktop, packaging, docs.
orchestration/checks/check-*.py — acceptance per phase.
orchestration/checks/final-gate.sh — clean regeneration + checks 10–160.
Golden drift gate — orchestration/golden/data-golden.json vs report/data.json (check-95).

Iteration log: pdca-log.md.

Data contracts and outputs

Artifact	Doc
`data.json`, `metrics.json`	data-contract.md
`pdp.json`, PDP interview	pdp.md
Reader wiki HTML	Generated under `<workspace>/report/wiki/`; see pipeline.md
Operator-facing help	operator-guide.md

Snapshot tooling

Workspace export — POST /api/export → <workspace>/snapshot.zip (flat layout).
Website snapshot — scripts/make-website-snapshot.sh → snapshots/feedback360-website-<UTC>Z.zip (nested top folder). Both use feedback360/export_snapshot.py.

Feature status

Implemented / not-implemented flags for every capability: feature-status.md.

Full list with one-liners: README.md.

Capablio