--- description: Systematic workflow for discovering and documenting every backend service, endpoint, protocol, and IPC mechanism that a Verkada device type interacts with. Produces firmware maps, interaction docs, architecture diagrams, and council-verified documentation. category: verkada --- flowchart TD _HEADER_[""]:::headerStyle classDef headerStyle fill:none,stroke:none subgraph _MAIN_[" "] %% Phase 1: Map Firmware Locations subgraph Phase1["Phase 1: Map Firmware Locations"] SELECT_DEVICE[Select Device Type
ACU, Camera, Sensor,
Alarm, Gateway, etc.] SELECT_DEVICE --> LIST_EXTRA[List extra-repos
firmware repos] SELECT_DEVICE --> SEARCH_MONO[Search monorepo
fan out Explore agents] SELECT_DEVICE --> READ_READMES[Read READMEs
and docs folders] SELECT_DEVICE --> CHECK_ORG[Check org chart
product-areas.json] LIST_EXTRA & SEARCH_MONO & READ_READMES & CHECK_ORG --> FIRMWARE_MAP[Output:
firmware-map.md] end %% Phase 2: Trace Device to Backend subgraph Phase2["Phase 2: Trace Device to Backend"] FIRMWARE_MAP --> SPAWN_FWD[Spawn Parallel
Sub-agents] SPAWN_FWD --> AGENT_PY[[Agent 1:
Python Code]] SPAWN_FWD --> AGENT_GO[[Agent 2:
Go Code]] SPAWN_FWD --> AGENT_IPC[[Agent 3:
IPC Mechanisms]] SPAWN_FWD --> AGENT_CFG[[Agent 4:
Config and Env]] AGENT_PY & AGENT_GO & AGENT_IPC & AGENT_CFG --> MERGE_FWD[Merge Findings] MERGE_FWD --> DEV_BACKEND_DOC[Output:
device-backend-interactions.md] end %% Phase 3: Trace Backend to Device (Reverse) subgraph Phase3["Phase 3: Trace Backend to Device"] DEV_BACKEND_DOC --> GROUP_SVCS[Group Services
by Size] GROUP_SVCS --> LARGE_SVC[[Large Services
vcerberus, vprovision]] GROUP_SVCS --> MEDIUM_SVC[[Medium Services
vmeerkat, vparrot, vinnout]] GROUP_SVCS --> SMALL_SVC[[Small Services
2-3 per agent]] GROUP_SVCS --> DOCS_READER[[Docs Reader
READMEs and docs]] LARGE_SVC & MEDIUM_SVC & SMALL_SVC & DOCS_READER --> MERGE_REV[Merge Reverse
Findings] MERGE_REV --> SVC_DEVICE_DOC[Output:
service-device-interactions.md] end %% Phase 4: Draw Diagram subgraph Phase4["Phase 4: Draw Diagram"] SVC_DEVICE_DOC --> LAYOUT[Design Diagram
Layout] LAYOUT --> SG_DEVICE[Subgraph:
Device Components] LAYOUT --> SG_CORE[Subgraph:
Core Backend] LAYOUT --> SG_EVENTS[Subgraph:
Event Pipeline] LAYOUT --> SG_FRONTEND[Subgraph:
Frontend Delivery] LAYOUT --> SG_STORAGE[Subgraph:
Storage] LAYOUT --> SG_INDIRECT[Subgraph:
Indirect Services] SG_DEVICE & SG_CORE & SG_EVENTS & SG_FRONTEND & SG_STORAGE & SG_INDIRECT --> RENDER[Render with mmdc
4000x6000 3x scale] RENDER --> DIAGRAM_OUT[Output:
diagram.mermaid + .png] end %% Phase 5: Council Review subgraph Phase5["Phase 5: Council Review to Convergence"] DIAGRAM_OUT --> COUNCIL_RUN[Run Council
Gemini + Codex] COUNCIL_RUN --> VERIFY{Errors
Found?} VERIFY -->|Yes| APPLY_FIXES[Apply Fixes
file paths, topics,
function names] APPLY_FIXES --> TRACK_ROUND[Track Round
and Fix Count] TRACK_ROUND --> COUNCIL_RUN VERIFY -->|No| CONVERGE_CHECK{Two Consecutive
Zero-Fix Rounds?} CONVERGE_CHECK -->|No| COUNCIL_RUN CONVERGE_CHECK -->|Yes| CONVERGED([Converged]) end %% Search pattern detail nodes (referenced in tooltips) click SELECT_DEVICE "#" "**Select Device Type**\nChoose which Verkada device family to trace:\n- ACU (access control)\n- Camera\n- Sensor\n- Alarm V1 / V2\n- Gateway\n- Intercom\n- Connect Box\n- Trailer\n\nEach device has different firmware locations and backend service dependencies." click LIST_EXTRA "#" "**List extra-repos**\nRun `ls ~/verkada/extra-repos/` to find device-family-specific firmware repos.\n\nExamples:\n- ACU: verkada-device-firmware, vreader_zephyr, wireless_lock\n- Camera: camera-firmware, camera-firmware-scripts\n- Alarm: alarms-firmware, alarms-layers\n- Intercom: intercom-firmware, meta-intercom" click SEARCH_MONO "#" "**Search Monorepo**\nFan out Explore agents to find device directories in Verkada-Backend.\n\nPrimary firmware directories by device:\n- ACU: `vaccess/`\n- Camera: `vcamera/`, `vfirmware_common/`\n- Sensor: `vsensor/`, `vsensorconfig/`\n- Alarm V1: `vwire/`, `valarm/`\n- Alarm V2: `vlead/`, `vprochronicle/`\n- Gateway: `vnet/`, `vcellular/`\n- Intercom: `vinter/`, `vpava/`\n- Connect Box: `vfortress/`" click READ_READMES "#" "**Read READMEs and Docs**\nRead every README.md and docs/ folder found in firmware directories.\nCaptures architecture notes, protocol descriptions, and known dependencies." click CHECK_ORG "#" "**Check Org Chart**\nRead `~/.claude/skills/verkada-org-chart/data/product-areas.json`\nto get the canonical service list for the product area.\nEnsures no services are missed." click FIRMWARE_MAP "#" "**Firmware Map Output**\nProduces `docs/events/{device}-firmware-map.md`\n\nContains:\n- All monorepo directories with device code\n- All extra-repos for the device family\n- README summaries and architecture notes\n- Canonical service list from org chart" click SPAWN_FWD "#" "**Spawn Parallel Sub-agents**\nFan out 4 parallel agents with `/ast-parsing` to search device-side code.\nEach agent covers a different search pattern category.\nRuns concurrently for speed." click AGENT_PY "#" "**Agent 1: Python Code**\nSearches device Python code for backend interactions:\n- `ast-grep --pattern 'requests.$METHOD($$$)'`\n- `grep -rn 'https?://'` for HTTP URLs\n- Service name references (vprovision, vauth, vcerberus, etc.)\n- Kafka/Redis patterns (topic, producer, consumer, pubsub)" click AGENT_GO "#" "**Agent 2: Go Code**\nSearches device Go code for backend interactions:\n- `ast-grep --pattern 'http.NewRequest($$$)'`\n- `ast-grep --pattern 'http.Get($$$)'`\n- `ast-grep --pattern 'grpc.Dial($$$)'` for gRPC\n- `grep -rn 'wss?://'` for WebSocket URLs\n- Service name references in .go files" click AGENT_IPC "#" "**Agent 3: IPC Mechanisms**\nSearches for inter-process communication:\n- ZeroMQ: `zmq`, `ZMQ`, `zeromq`, `ipc://`\n- Unix sockets: `unix://`, `/tmp/`, `/var/run`\n- gRPC over Unix sockets\n- Proto files: `find -name '*.proto'`" click AGENT_CFG "#" "**Agent 4: Config and Environment**\nSearches for environment-specific configuration:\n- Shard URLs: prod1, prod2, staging, prod-ap-syd\n- Config file paths: `/mnt/`, `/data/`, `/config/`\n- ETag/If-None-Match patterns (config caching)\n- Buffer directories (retry queues)" click MERGE_FWD "#" "**Merge Findings**\nCombine results from all 4 parallel agents.\nDeduplicate endpoints, group by service,\nidentify protocol types (HTTP, gRPC, WebSocket, Kafka, IPC)." click DEV_BACKEND_DOC "#" "**Device-Backend Interactions Doc**\nProduces `docs/events/{device}-backend-interactions.md`\n\nContains every backend URL, endpoint, protocol,\nKafka topic, Redis channel, and IPC mechanism\nthe device uses, organized by service." click GROUP_SVCS "#" "**Group Services by Size**\nEfficiency optimization for parallel tracing:\n- Large services (vcerberus, vprovision): one agent each\n- Medium services (vmeerkat, vparrot, vinnout): one agent each\n- Small services: group 2-3 per agent\n- Separate docs reader agent" click LARGE_SVC "#" "**Large Services**\nOne dedicated agent per large service.\nSearches for:\n- `@$APP.route($$$)` Flask endpoints\n- Kafka topics produced/consumed\n- Redis pub/sub patterns\n- Outbound HTTP to other services\n- DynamoDB/SQS/S3 usage\n- WebSocket handlers\n- CDC (Debezium) topics" click MEDIUM_SVC "#" "**Medium Services**\nOne agent per medium service (vmeerkat, vparrot, vinnout).\nSame search patterns as large services:\n- HTTP endpoints, Kafka, Redis, cross-service calls,\n AWS resources, WebSocket, CDC topics." click SMALL_SVC "#" "**Small Services**\nGroup 2-3 small services per agent.\nExamples: vtailgate + vaccess_cv + vautomations.\nSame search patterns but combined for efficiency." click DOCS_READER "#" "**Docs Reader**\nSeparate agent reads all README.md and docs/ files\nfor each backend service.\nCaptures architecture decisions, protocol specs,\nand known integration points." click MERGE_REV "#" "**Merge Reverse Findings**\nCombine results from all backend service agents.\nFor each service, document:\n- Endpoints exposed to devices\n- Commands sent via vmeerkat WebSocket\n- Config push triggers\n- Events published to Kafka/Redis" click SVC_DEVICE_DOC "#" "**Service-Device Interactions Doc**\nProduces `docs/events/{device}-service-device-interactions.md`\n\nContains how each backend service reaches the device:\n- Flask/Fiber endpoints\n- WebSocket commands\n- Config reload triggers\n- CDC topic consumption\n- SQS/Lambda invocations" click LAYOUT "#" "**Design Diagram Layout**\nStructure the Mermaid flowchart with 6 subgraphs:\n- Device (firmware layers, IPC)\n- Core Backend (direct device contact)\n- Event Pipeline (Kafka, vevents, vlive)\n- Frontend Delivery (WebSocket, clients)\n- Storage (S3, Redis, DynamoDB, SQS)\n- Indirect Services (no direct device contact)" click SG_DEVICE "#" "**Subgraph: Device Components**\nOn-device firmware layers and IPC mechanisms.\nShows internal communication paths\nbetween device processes." click SG_CORE "#" "**Subgraph: Core Backend**\nServices with direct device contact.\nHTTP endpoints, gRPC, WebSocket connections\nthat the device actively communicates with." click SG_EVENTS "#" "**Subgraph: Event Pipeline**\nKafka topics, vevents, vlive, vmercury.\nShows how device events flow through\nthe event processing infrastructure." click SG_FRONTEND "#" "**Subgraph: Frontend Delivery**\nWebSocket gateways, web and mobile clients.\nShows how processed events reach\nend users in Command." click SG_STORAGE "#" "**Subgraph: Storage**\nS3, Redis, DynamoDB, SQS.\nShows where device data is persisted\nand async processing queues." click SG_INDIRECT "#" "**Subgraph: Indirect Services**\nServices that interact with device data\nbut have no direct device contact.\nReach devices through other services." click RENDER "#" "**Render with mmdc**\nGenerate high-res PNG from Mermaid:\n`PUPPETEER_EXECUTABLE_PATH=... mmdc -i diagram.mermaid -o diagram.png -w 4000 -H 6000 --scale 3`" click DIAGRAM_OUT "#" "**Diagram Output**\nProduces:\n- `docs/events/{device}-backend-diagram.mermaid`\n- `docs/events/{device}-backend-diagram.png`\n\nVisual architecture showing all interactions\nbetween device and backend services." click COUNCIL_RUN "#" "**Run Council**\nVerify every claim against source code:\n`council --yolo -C --timeout 900`\n\nCouncil (Gemini + Codex) independently verify:\n- File paths and line numbers\n- Function names and signatures\n- Kafka topics and config values\n- Missing services or connections" click VERIFY "#" "**Errors Found?**\nCouncil reports verified factual errors:\n- Wrong file paths or line numbers\n- Incorrect function names\n- Missing Kafka topics or connections\n- Stale references\n\nAlso flags missing services visible in code but absent from docs." click APPLY_FIXES "#" "**Apply Fixes**\nFix all confirmed errors:\n- Correct file paths and line numbers\n- Update function names\n- Add missing Kafka topics\n- Add newly discovered connections\n\nCouncil often discovers new nodes (graph exploration pattern)." click TRACK_ROUND "#" "**Track Round and Fix Count**\nTrack using Claude Code TaskList:\n- Each task: 'Trace + council: {service} ({role})'\n- Status: pending, in_progress, completed\n- Round counts: R1, R2, R3...\n- Fix counts per round (should trend downward)\n\nHistorical: Layer 1 averaged 5-7 rounds, 10-38 fixes." click CONVERGE_CHECK "#" "**Two Consecutive Zero-Fix Rounds?**\nStrict convergence: two consecutive rounds where\nboth Gemini AND Codex report 0 errors.\n\nTrend convergence (marked with *): fix count clearly\ndeclining, remaining errors are deep nuances.\nUsed for complex docs with long tails." click CONVERGED "#" "**Converged**\nDocumentation is verified against source code.\nAll three artifacts are complete:\n1. Firmware map\n2. Interaction docs (both directions)\n3. Architecture diagram\n\nReady for the next device type or layer." classDef firmware fill:#d1ecf1,stroke:#7ec8d8 classDef trace_fwd fill:#e8daef,stroke:#b07cc6 classDef trace_rev fill:#ffeaa7,stroke:#e0c040 classDef diagram fill:#dfe6ff,stroke:#5b7bce classDef council fill:#fff3cd,stroke:#f0c040 classDef output fill:#d4edda,stroke:#5cb85c classDef decision fill:#fff3cd,stroke:#f0c040 class SELECT_DEVICE,LIST_EXTRA,SEARCH_MONO,READ_READMES,CHECK_ORG firmware class FIRMWARE_MAP,DEV_BACKEND_DOC,SVC_DEVICE_DOC,DIAGRAM_OUT output class SPAWN_FWD,AGENT_PY,AGENT_GO,AGENT_IPC,AGENT_CFG,MERGE_FWD trace_fwd class GROUP_SVCS,LARGE_SVC,MEDIUM_SVC,SMALL_SVC,DOCS_READER,MERGE_REV trace_rev class LAYOUT,SG_DEVICE,SG_CORE,SG_EVENTS,SG_FRONTEND,SG_STORAGE,SG_INDIRECT,RENDER diagram class COUNCIL_RUN,APPLY_FIXES,TRACK_ROUND council class VERIFY,CONVERGE_CHECK decision class CONVERGED output end style _MAIN_ fill:none,stroke:none,padding:0 _HEADER_ ~~~ _MAIN_