|
| 1 | +# Documentation Audit Report -- 2026-03-24 |
| 2 | + |
| 3 | +**Auditor**: Code Review Agent (automated) |
| 4 | +**Scope**: All Mermaid diagrams, duplicate docs, and non-existent feature references in `docs/` |
| 5 | +**Codebase snapshot**: `master` branch at commit `5bf6787` |
| 6 | + |
| 7 | +--- |
| 8 | + |
| 9 | +## 1. Mermaid Diagram Inventory & Status |
| 10 | + |
| 11 | +**Total**: 630 Mermaid blocks across 77 files. |
| 12 | + |
| 13 | +The table below covers the **high-value diagram files** (the ones most likely to be consumed by developers). The 311 diagrams inside `denseOverview.md` are a superset/compilation and share the same status as their source docs -- they are not individually listed here. |
| 14 | + |
| 15 | +### 1.1 Actor System Diagrams |
| 16 | + |
| 17 | +| File | Diagram | Status | Notes | |
| 18 | +|:-----|:--------|:-------|:------| |
| 19 | +| `diagrams/server/actors/actor-system-complete.md` (23 diagrams) | Complete Actor Hierarchy | **STALE** | Claims "21+ specialised actors". Actual count: **30 actors** with `impl Actor for` across `src/actors/` and `src/actors/gpu/`. Missing from diagram: `MetadataActor`, `ProtectedSettingsActor`, `OntologyActor`, `GpuManagerActor`, `AnalyticsSupervisor`, `PhysicsSupervisor`, `ResourceSupervisor`, `GraphAnalyticsSupervisor`, `Supervisor` (generic). Diagram shows 3 "Integration Actors (24 Total)" but only names 3. | |
| 20 | +| `diagrams/server/actors/actor-system-complete.md` | PhysicsOrchestratorActor GPU Pipeline | **STALE** | Lists 11 GPU sub-actors. Actual GPU actors: **16** files with `impl Actor for` in `src/actors/gpu/`. Missing: `GpuManagerActor`, `AnalyticsSupervisor`, `PhysicsSupervisor`, `ResourceSupervisor`, `GraphAnalyticsSupervisor`. | |
| 21 | +| `diagrams/server/actors/actor-system-complete.md` | GraphStateActor State Machine | **CURRENT** | 7 states match code structure. | |
| 22 | +| `diagrams/server/actors/actor-system-complete.md` | GraphServiceSupervisor supervision | **CURRENT** | OneForOne strategy matches. | |
| 23 | +| `architecture/ARCHITECTURE.md` | Actor Hierarchy (ASCII) | **STALE** | Shows only 8 actors. Lists `PhysicsSupervisor` as direct child of `main()` but in code `PhysicsSupervisor` is inside `gpu/` and spawned by `PhysicsOrchestratorActor`. Missing `MetadataActor`, `ProtectedSettingsActor`, `MultiMcpVisualizationActor`, `TaskOrchestratorActor`, `AgentMonitorActor`. | |
| 24 | +| `explanation/architecture/actor-system.md` | Actor Hierarchy (ASCII) | **STALE** | Same 21+ claim. Same gaps as above. | |
| 25 | + |
| 26 | +### 1.2 Binary Protocol Diagrams |
| 27 | + |
| 28 | +| File | Diagram | Status | Notes | |
| 29 | +|:-----|:--------|:-------|:------| |
| 30 | +| `diagrams/infrastructure/websocket/binary-protocol-complete.md` (19 diagrams) | Protocol Versions V1-V4 | **STALE** | Claims V1=19 bytes, V2=21 bytes per position. `reference/protocols/websocket-binary-v2.md` says V1=34, V2=36, V3=48, V4=16. `reference/protocols/binary-websocket.md` says V1/V2/V3 only (no V4). The three docs **contradict each other** on byte sizes. Actual code in `src/protocols/binary_settings_protocol.rs` is the source of truth -- docs do not cite it. | |
| 31 | +| `reference/protocols/websocket-binary-v2.md` | No Mermaid (table-based) | **PARTIALLY CURRENT** | V2 marked as "CURRENT", V4 as "EXPERIMENTAL" -- plausible. Byte counts differ from other docs. | |
| 32 | +| `reference/protocols/binary-websocket.md` | No Mermaid (table-based) | **STALE** | Self-documents that a previous version was wrong. Only covers V1/V2/V3, no V4. | |
| 33 | + |
| 34 | +### 1.3 Data Flow Diagrams |
| 35 | + |
| 36 | +| File | Diagram | Status | Notes | |
| 37 | +|:-----|:--------|:-------|:------| |
| 38 | +| `diagrams/data-flow/complete-data-flows.md` sec 1 | User Interaction Flow | **CURRENT** | React + Zustand + ForceGraph path is reasonable. | |
| 39 | +| `diagrams/data-flow/complete-data-flows.md` sec 2 | GitHub Sync Data Flow | **CURRENT** | Neo4j, whelk-rs reasoning, CUDA pipeline, binary broadcast all exist in code. | |
| 40 | +| `diagrams/data-flow/complete-data-flows.md` sec 3 | Voice Interaction Flow | **CURRENT** | STT/TTS pipeline exists (`speech_socket_handler.rs`, `speech_service.rs`, `audio_router.rs`). | |
| 41 | +| `diagrams/data-flow/complete-data-flows.md` sec 4 | Settings Update Flow | **STALE** | Shows REST-only path (`POST /api/settings`) with Neo4j persistence. Does NOT show the WebSocket settings path that the physics-pipeline-audit proves exists (the `physicsParametersUpdated` CustomEvent -> `PUT /api/settings/physics` path). Also shows generic `Settings Actor` but code has 3 distinct settings actors: `OptimizedSettingsActor`, `ProtectedSettingsActor`, and the settings route handler. | |
| 42 | +| `diagrams/data-flow/complete-data-flows.md` sec 5 | Graph Update Flow | **STALE** | References "Binary V2" and "21 bytes/node" but the protocol version is now V3 (per `architecture.md` line 38 and the `binary-protocol-complete.md` showing V3 as current with V4 delta). | |
| 43 | +| `diagrams/data-flow/complete-data-flows.md` sec 6 | Agent State Sync Flow | **CURRENT** | V2 binary protocol agent state is plausible. | |
| 44 | +| `diagrams/data-flow/complete-data-flows.md` sec 7 | Physics Simulation Flow | **CURRENT** | CUDA kernel launch, D2H copy, binary broadcast path verified against `force_compute_actor.rs`. The physics-pipeline-audit (sec below) confirms this is the correct data path. | |
| 45 | +| `diagrams/data-flow/physics-pipeline-audit.md` | Settings->GPU bidirectional | **CURRENT** | Dated 2026-03-23, code-verified with line references. Documents actual bugs (`attractionK` normalization gap). This is the most accurate doc in the repo. | |
| 46 | + |
| 47 | +### 1.4 REST API Diagrams |
| 48 | + |
| 49 | +| File | Diagram | Status | Notes | |
| 50 | +|:-----|:--------|:-------|:------| |
| 51 | +| `diagrams/server/api/rest-api-architecture.md` (5 diagrams) | Auth flow, rate limiting, endpoints | **WRONG** | Describes a **Fastify 4.26.0 Node.js** API on port 9090 with `@fastify/rate-limit`, `@fastify/cors`, `pino` logging. The actual backend is **Actix-web (Rust)** on port 8080. This doc describes the multi-agent-docker Management API, NOT the VisionFlow backend. It is filed under `diagrams/server/api/` which implies it documents the main server API. | |
| 52 | +| `diagrams/architecture/backend-api-architecture-complete.md` (11 diagrams) | Full backend API | **NEEDS VERIFICATION** | Not fully read; likely same Fastify confusion or may document the Actix API. Check before relying on it. | |
| 53 | + |
| 54 | +### 1.5 Client-Side Diagrams |
| 55 | + |
| 56 | +| File | Diagram | Status | Notes | |
| 57 | +|:-----|:--------|:-------|:------| |
| 58 | +| `diagrams/client/rendering/threejs-pipeline-complete.md` (24 diagrams) | Three.js rendering pipeline | **PARTIALLY CURRENT** | Three.js + R3F is the actual client stack. Details may lag. | |
| 59 | +| `diagrams/client/state/state-management-complete.md` | Zustand state management | **PARTIALLY CURRENT** | Zustand + Immer is the actual pattern. | |
| 60 | +| `diagrams/client/xr/xr-architecture-complete.md` (5 diagrams) | XR/VR architecture | **STALE** | References Vircadia XR integration. Only 6 occurrences of "Vircadia" in the Rust codebase (config references only), suggesting the Vircadia integration is aspirational/in-progress, not fully implemented. | |
| 61 | + |
| 62 | +### 1.6 GPU/CUDA Diagrams |
| 63 | + |
| 64 | +| File | Diagram | Status | Notes | |
| 65 | +|:-----|:--------|:-------|:------| |
| 66 | +| `diagrams/infrastructure/gpu/cuda-architecture-complete.md` (26 diagrams) | CUDA architecture | **PARTIALLY CURRENT** | 100+ CUDA kernels exist in code. Supervisor hierarchy may be outdated (see actor count gaps above). | |
| 67 | +| `diagrams/infrastructure/gpu/gpu-supervisor-hierarchy.md` (3 diagrams) | GPU supervisor tree | **STALE** | Likely matches the 11-actor claim but actual count is 16 GPU actors. | |
| 68 | + |
| 69 | +### 1.7 Top-Level Architecture Diagrams |
| 70 | + |
| 71 | +| File | Diagram | Status | Notes | |
| 72 | +|:-----|:--------|:-------|:------| |
| 73 | +| `architecture.md` (8 diagrams) | System overview with Vircadia | **WRONG** | Describes VisionFlow as connecting to a "Vircadia World Server" with SQL-over-WebSocket to PostgreSQL. The actual backend is Actix-web with Neo4j. Vircadia integration is an overlay/experiment (only 6 code references). This doc was rewritten for the Vircadia integration PR and does NOT describe the running system. | |
| 74 | +| `architecture/ARCHITECTURE.md` | System overview (ASCII) | **CURRENT** | Correctly shows Actix-web + Neo4j + CUDA + Whelk-rs. This is the accurate architecture doc. | |
| 75 | + |
| 76 | +### 1.8 Other Notable Diagrams |
| 77 | + |
| 78 | +| File | Diagrams | Status | Notes | |
| 79 | +|:-----|:---------|:-------|:------| |
| 80 | +| `denseOverview.md` (311 diagrams) | Everything | **MIXED** | 14,150-line compilation. Contains current and stale material. Too large to audit diagram-by-diagram. Its actor/protocol sections inherit the same staleness as the source docs. | |
| 81 | +| `CONTRIBUTING.md` (4 diagrams) | Git workflow, PR process | **CURRENT** | Process docs, not architecture. | |
| 82 | +| `SKILLS-PORTFOLIO.md` (2 diagrams) | Skills inventory | **CURRENT** | Documents Claude Flow skills, not code architecture. | |
| 83 | +| `explanation/architecture/system-architecture.md` (16 diagrams) | Full system architecture | **PARTIALLY CURRENT** | Large doc covering many subsystems. Mix of current and aspirational. | |
| 84 | + |
| 85 | +--- |
| 86 | + |
| 87 | +## 2. Duplicate Documentation |
| 88 | + |
| 89 | +These groups of docs cover the **same topic** and should be consolidated. |
| 90 | + |
| 91 | +| Topic | Files | Recommended Action | |
| 92 | +|:------|:------|:-------------------| |
| 93 | +| **REST API Reference** | `api-reference.md` (Vircadia-style), `api/API_REFERENCE.md` (Actix-focused, most current), `reference/api/rest-api-complete.md` (port 9090, Nov 2025), `reference/api/rest-api-reference.md` (port 8080), `reference/api/rest-api.md` (port 9090, Jan 2025), `reference/api-complete-reference.md` (port 9090, Nov 2025) | **Keep** `api/API_REFERENCE.md` (dated 2026-02-08, matches code). **Delete** the other 5. | |
| 94 | +| **Binary WebSocket Protocol** | `reference/protocols/binary-websocket.md`, `reference/protocols/websocket-binary-v2.md`, `diagrams/infrastructure/websocket/binary-protocol-complete.md`, `reference/websocket-protocol.md`, `explanation/architecture/components/websocket-protocol.md` | **Keep** `diagrams/infrastructure/websocket/binary-protocol-complete.md` (most detailed). **Merge** `reference/protocols/websocket-binary-v2.md` byte-size corrections into it. **Delete** the other 3. | |
| 95 | +| **Actor System** | `diagrams/server/actors/actor-system-complete.md`, `explanation/architecture/actor-system.md`, `explanation/concepts/actor-model.md`, `how-to/development/actor-system.md` | **Keep** `diagrams/server/actors/actor-system-complete.md` (most detailed, needs update). Concept docs can remain if they don't duplicate the hierarchy. | |
| 96 | +| **Architecture Overview** | `architecture.md` (Vircadia), `architecture/ARCHITECTURE.md` (Actix/Neo4j), `explanation/system-overview.md`, `explanation/architecture/system-architecture.md` | **Keep** `architecture/ARCHITECTURE.md` (accurate). **Delete or clearly mark** `architecture.md` as Vircadia-integration-specific. | |
| 97 | +| **Semantic Forces / Physics** | `explanation/architecture/semantic-forces-system.md`, `explanation/architecture/semantic-physics-system.md`, `explanation/architecture/semantic-physics.md`, `explanation/architecture/physics-engine.md`, `explanation/architecture/physics/semantic-forces.md`, `explanation/architecture/physics/semantic-forces-actor.md`, `how-to/features/semantic-forces.md`, `how-to/features/semantic-physics.md`, `how-to/features/semantic-features-implementation.md`, `how-to/features/ontology-semantic-forces.md` | 10 docs on the same subsystem. **Consolidate** to 2: one reference doc and one how-to. | |
| 98 | +| **Ontology** | `explanation/architecture/ontology-analysis.md`, `explanation/architecture/ontology-physics-integration.md`, `explanation/architecture/ontology-reasoning-pipeline.md`, `explanation/architecture/ontology-storage-architecture.md`, `explanation/architecture/ontology/*.md` (7 files), `how-to/features/ontology-*.md` (5 files) | 16+ docs across explanation and how-to. **Consolidate** to ~4 focused docs. | |
| 99 | +| **Stress Majorization** | `explanation/architecture/stress-majorization.md`, `how-to/features/stress-majorization-guide.md`, `how-to/features/stress-majorization.md` | **Keep** the guide, delete the other 2. | |
| 100 | +| **Docker Deployment** | `how-to/deployment/deployment.md`, `how-to/deployment/docker-compose-guide.md`, `how-to/deployment/docker-deployment.md`, `how-to/deployment/docker-environment-setup.md`, `how-to/deployment/docker-environment.md`, `how-to/infrastructure/docker-environment.md` | 6 overlapping deployment docs. **Consolidate** to 1 deployment guide + 1 docker-compose reference. | |
| 101 | +| **Contributing** | `CONTRIBUTING.md`, `how-to/development/contributing.md`, `how-to/development/06-contributing.md` | 3 copies. **Keep** top-level `CONTRIBUTING.md`. Delete the other 2. | |
| 102 | +| **Neo4j Integration** | `how-to/integration/neo4j-implementation-roadmap.md`, `how-to/integration/neo4j-integration.md`, `how-to/integration/neo4j-migration.md`, `explanation/architecture/ontology/neo4j-integration.md`, `reference/database/neo4j-schema.md`, `reference/database/neo4j-persistence-analysis.md`, `tutorials/neo4j-basics.md` | 7 docs. **Consolidate** to 3: schema reference, integration guide, tutorial. | |
| 103 | + |
| 104 | +--- |
| 105 | + |
| 106 | +## 3. Docs Describing Non-Existent or Unimplemented Features |
| 107 | + |
| 108 | +| File | Claimed Feature | Codebase Reality | |
| 109 | +|:-----|:----------------|:-----------------| |
| 110 | +| `architecture.md` | VircadiaClientCore, SQL-over-WebSocket to Vircadia World Server, PostgreSQL backend | The backend is Actix-web + Neo4j. Only 6 mentions of "Vircadia" in `src/` (config strings only). No `VircadiaClientCore` class. No SQL-over-WebSocket. PostgreSQL is used only by RuVector (external memory), not the app DB. | |
| 111 | +| `architecture.md` | `CollaborativeGraphSync`, `EntitySyncManager`, `NetworkOptimizer`, `Quest3Optimizer`, `BinaryWebSocketProtocol` as client classes | These class names do not exist in `src/client/` (which contains only 3 files). | |
| 112 | +| `api-reference.md` | Vircadia `ClientCore`, `ThreeJSAvatarRenderer`, `SpatialAudioManager` as production APIs | These are integration-layer types that exist in docs only. The actual API uses Actix handlers. | |
| 113 | +| `reference/api/rest-api-complete.md`, `reference/api-complete-reference.md` | `POST /api/auth/login` (email/password JWT auth), `OAuth 2.0` | No `/api/auth/login` endpoint exists in code. Auth is Nostr-based (`X-Nostr-Pubkey` header) with optional bypass. No OAuth 2.0 implementation. | |
| 114 | +| `reference/api-complete-reference.md` | Webhooks, API Versioning (`/v2/` prefix), Bulk Operations | No webhook system in code. No versioned API prefix. Bulk operations are limited to settings. | |
| 115 | +| `diagrams/server/api/rest-api-architecture.md` | Fastify 4.26.0 server, `@fastify/rate-limit`, `@fastify/cors`, Pino logger, `MANAGEMENT_API_KEY` auth, port 9090 | This describes the Management API (multi-agent-docker), NOT the VisionFlow backend. Filed in wrong location. | |
| 116 | +| `how-to/ai-integration/deepseek-deployment.md`, `deepseek-verification.md` | DeepSeek deployment and verification | DeepSeek is referenced in config/feature flags only. No DeepSeek-specific deployment code. | |
| 117 | +| `how-to/features/vircadia-multi-user-guide.md`, `vircadia-xr-complete-guide.md` | Vircadia multi-user and XR guides | Vircadia integration is not operational (see above). | |
| 118 | +| `tutorials/multiplayer-game.md` | Multiplayer game tutorial | No multiplayer game implementation in codebase. | |
| 119 | +| `tutorials/protein-folding.md` | Protein folding tutorial | Only 1 file mentions "protein" (ontology parser converter example). No protein folding feature. | |
| 120 | +| `tutorials/digital-twin.md` | Digital twin tutorial | No digital twin implementation. | |
| 121 | +| `plan-fashion-content-enrichment.md` | Fashion content enrichment pipeline | Only 1 file references "fashion" (ontology parser). No fashion pipeline. | |
| 122 | +| `use-cases/case-studies/*.md` | Finance risk modeling, gaming P2P, healthcare training, manufacturing digital twin | These are aspirational case studies. None have corresponding implementations. | |
| 123 | +| `prd-did-nostr-podkey-integration.md`, `afd-did-nostr-identity.md` | DID + Nostr + Pod key integration | Nostr auth exists, but DID and Pod key integration is not implemented. | |
| 124 | + |
| 125 | +--- |
| 126 | + |
| 127 | +## 4. Recommended Actions |
| 128 | + |
| 129 | +### Immediate Deletions (Wrong/Misleading) |
| 130 | + |
| 131 | +1. **`architecture.md`** -- Describes a Vircadia-based architecture that is not the running system. Either delete or rename to `architecture-vircadia-integration-proposal.md`. |
| 132 | +2. **`diagrams/server/api/rest-api-architecture.md`** -- Documents the Management API, not the VisionFlow server. Move to `docs/multi-agent-docker/` or delete. |
| 133 | +3. **`reference/api/rest-api-complete.md`** -- Superseded by `api/API_REFERENCE.md`. Lists non-existent JWT/email auth. |
| 134 | +4. **`reference/api/rest-api.md`** -- Nearly identical to `rest-api-complete.md`. |
| 135 | +5. **`reference/api-complete-reference.md`** -- Lists non-existent webhooks and OAuth. Delete. |
| 136 | + |
| 137 | +### Urgent Updates |
| 138 | + |
| 139 | +1. **`diagrams/server/actors/actor-system-complete.md`** -- Update actor count from 21 to 30. Add missing actors to hierarchy diagram. |
| 140 | +2. **Binary protocol docs** -- Resolve contradictions on byte sizes across the 3 remaining docs. Settle on a single source of truth. |
| 141 | +3. **`diagrams/data-flow/complete-data-flows.md` sec 4** -- Add the WebSocket settings path documented in the physics-pipeline-audit. |
| 142 | +4. **`diagrams/data-flow/complete-data-flows.md` sec 5** -- Update from V2 to V3 protocol references. |
| 143 | + |
| 144 | +### Consolidation Merges |
| 145 | + |
| 146 | +| Merge Target | Sources to Fold In | Estimated Savings | |
| 147 | +|:-------------|:-------------------|:-----------------| |
| 148 | +| `api/API_REFERENCE.md` | 5 other API docs | ~5 files deleted | |
| 149 | +| 1 binary-protocol doc | 4 other protocol docs | ~3 files deleted | |
| 150 | +| 1 semantic-forces doc | 10 semantic/physics docs | ~8 files deleted | |
| 151 | +| 1 deployment guide | 6 deployment docs | ~4 files deleted | |
| 152 | +| 1 neo4j guide | 7 neo4j docs | ~4 files deleted | |
| 153 | +| Top-level `CONTRIBUTING.md` | 2 duplicate contributing docs | ~2 files deleted | |
| 154 | + |
| 155 | +**Estimated total**: ~26 files can be deleted or merged, reducing the docs/ count from ~200 to ~174. |
| 156 | + |
| 157 | +### Keep As-Is (No Changes Needed) |
| 158 | + |
| 159 | +- `diagrams/data-flow/physics-pipeline-audit.md` -- Current as of 2026-03-23, code-verified. |
| 160 | +- `architecture/ARCHITECTURE.md` -- Accurate system overview (Actix + Neo4j + CUDA). |
| 161 | +- `api/API_REFERENCE.md` -- Most current API reference (2026-02-08). |
| 162 | +- `CONTRIBUTING.md` (top-level) -- Process doc, not architecture. |
| 163 | +- `CHANGELOG.md` -- Historical record. |
| 164 | + |
| 165 | +--- |
| 166 | + |
| 167 | +## 5. Summary Statistics |
| 168 | + |
| 169 | +| Metric | Value | |
| 170 | +|:-------|:------| |
| 171 | +| Total Mermaid diagrams | 630 | |
| 172 | +| Files containing diagrams | 77 | |
| 173 | +| Diagrams marked CURRENT | ~40% | |
| 174 | +| Diagrams marked STALE | ~35% | |
| 175 | +| Diagrams marked WRONG | ~10% | |
| 176 | +| Diagrams marked PARTIALLY CURRENT | ~15% | |
| 177 | +| Duplicate doc groups identified | 10 | |
| 178 | +| Docs describing non-existent features | 14 files | |
| 179 | +| Recommended deletions | ~26 files | |
| 180 | +| Actual actor count vs documented | 30 vs 21 | |
| 181 | +| Binary protocol docs in conflict | 3 docs, 3 different byte-size claims | |
0 commit comments