# Systems Architecture Whiteboard — Complete User & Operator Guide Candidate: **Bhamidipati, Shiridi Prasad Revanth** Role Track: Senior Full-Stack Engineer / Distributed Systems Architect Interface: Interactive Spatial Architecture Whiteboard (`whiteboard.html`) --- ## 1. Getting Started ### Local Server Setup The Systems Architecture Whiteboard is fully self-contained and engineered to run under both local HTTP servers and direct filesystem browser access (`file://`). To launch the local HTTP server: ```bash cd /Users/revanthbsp/desktop/portfolio/complete-portfolio ./start_server.sh ``` The server will bind to `127.0.0.1:8089`. Once active, open the following URLs in any modern desktop or mobile browser (Chrome, Safari, Firefox, Edge): - **Systems Architecture Whiteboard:** `http://127.0.0.1:8089/whiteboard.html` - **Main Portfolio Homepage:** `http://127.0.0.1:8089/index.html` To stop the server: ```bash ./stop_server.sh ``` To restart the server: ```bash ./stop_server.sh && ./start_server.sh ``` --- ## 2. Understanding the Canvas The canvas is an infinite, 3200 × 2000 px spatial engineering stage with a subtle dot grid (28px spacing) modeled after Miro and FigJam engineering whiteboards. ### Canvas Elements & Visual Grammar 1. **Architecture Nodes (Cards):** - Each card represents a discrete system component, microservice, hardware endpoint, or pipeline stage. - **Header Strip:** Displays the tier classification (e.g. `TIER 1 · CLIENT ENTRY`) and framework stack (e.g. `ANGULAR SPA`). - **Title:** Name of the component. - **Purpose:** Production engineering explanation and architectural role. - **Technology Tags:** Pill tags indicating language, protocols, and libraries. - **Metric Strip:** Production-verified metrics (e.g. `200+ Field Agencies`, `8.2s → 4.1s (-50%)`). 2. **C4 Boundary Containers:** - Semi-transparent bordered regions encapsulating systems within verified architectural domains. - Labeled with the boundary scope (e.g. `C4 Container · GovTech Titling & Print Subnet Platform`). 3. **Directional Vector Connectors (SVG):** - Bezier curves connecting upstream producer nodes to downstream consumer nodes. - Directional arrowheads explicitly indicate data and control flow directions. 4. **Protocol & Data Contract Pills:** - Positioned midpoint along connector curves (e.g. `TCP Sockets :9100`, `JSON-RPC 2.0 / MCP Stdio`, `REST JSON (TLS 1.3)`). 5. **Engineering Sticky Notes:** - Distinctively colored sticky notes (Yellow, Cyan, Purple) documenting architectural trade-offs, design rationale, and performance benchmarks. --- ## 3. Changing Views The whiteboard provides 3 architectural viewing modes via the top navigation toolbar: | View Mode | Icon | Purpose & Behavior | | :--- | :---: | :--- | | **Whiteboard (Spatial)** | `☩` | Default freeform spatial engineering canvas with dynamic SVG connectors, pan, cursor-centered zoom, and drag-and-drop node positioning. | | **C4 Container View** | `⊡` | Elevates container boundaries and network isolation per the C4 model. Emphasizes subnets, DMZ perimeters, and trust boundaries. | | **Linear Document View** | `☰` | Top-to-bottom structured document view designed for sequential executive reading, screen readers, and high-density technical analysis. Connectors and minimap are collapsed to allow vertical scrolling. | --- ## 4. Exploring Architectural Domains The whiteboard visualizes 4 verified, production-grade engineering domains: 1. **GovTech Titling Platform (`GovTech`):** - *System:* NCDOT State Vehicle Titling & Instant Print Automation Platform. - *Architecture:* 4-tier system (Angular SPA Client → C# .NET Core Microservices → Subnet IP Socket Print Broker → 200+ LPA Hardware Printers). - *Verified Impact:* 200+ statewide agencies, 1.2M citizens served, print validation latency cut from 8.2s to 4.1s (-50%), $180,000 annual operational savings. 2. **Oracle Fusion HCM Cloud (`Oracle HCM`):** - *System:* Enterprise ERP & Payroll Ingestion Pipeline (Cognizant). - *Architecture:* Multi-tier ingestion (HDL/HSDL Batch Loaders → Oracle Cloud HCM Core Relational Models → Fast Formulas Calculation Engine → Relational Audit Ledger). - *Verified Impact:* Unified 40+ business entities, 50,000+ employees handled, query plan tuning and indexing saved 120 hours monthly. 3. **Edge Neural Vision (`Edge Vision`):** - *System:* On-Device Neural Document Classification & Silicon Camera Hardware Gating. - *Architecture:* 3-layer system (C/C++ Silicon Frame Hook → Quantized Mobile CNN Inference → Hardware Camera Driver Lockout Governor). - *Verified Research:* Published in IEEE CCICS 2025. Halts confidential document leakage directly at the camera sensor level. 4. **Cognitive Agent Tooling (`Documan MCP`):** - *System:* Model Context Protocol Knowledge Engine (Documan.ai). - *Architecture:* Frontier AI Agents (Claude Code, Cursor) → Documan Native MCP Server (JSON-RPC 2.0 / Stdio) → 200K+ Document Knowledge Store (Docker, Prometheus). - *Verified Impact:* Zero-glue integration for frontier LLMs, sub-millisecond retrieval across 200,000+ technical documentation pages. Clicking any domain button in the top toolbar smoothly animates the camera to frame that specific cluster. --- ## 5. Reading a Workflow Simulation The workflow controller simulates real execution transactions traveling across components: - **Active Path:** The SVG connector path currently transporting data lights up with a high-speed flowing cyan dash stroke (`stroke: #38BDF8; stroke-dasharray: 8 6; animation: rapidflow 1.2s linear infinite;`). - **Active Node:** The component actively processing or receiving the transaction glows with an animated cyan border pulse (`box-shadow: 0 0 24px rgba(56, 189, 248, 0.35)`). - **Stage Metadata:** The bottom controller HUD updates with the current stage index (e.g. `Stage 2 of 4: C# Microservices Tax & Document Engine`) and description. --- ## 6. Controlling Playback The Workflow Player HUD is docked at the bottom-center of the screen: - **`◀ Prev`:** Steps backward to the previous execution stage. - **`▶ Play Flow` / `⏸ Pause Flow`:** Starts or pauses automatic simulation progression (advances every 2.8 seconds). Pressing `Space` also toggles this. - **`↺ Replay`:** Restarts the simulation from Stage 1. - **`Next ▶`:** Steps forward to the next execution stage. - **Stage Pills (`01`, `02`, `03`, `04`):** Click any numbered pill to jump directly to that transaction stage. --- ## 7. Inspecting Component Dossiers & Verified Actions Clicking any architecture node card (or focusing on it and pressing `Enter`) slides open the **Architectural Dossier Drawer** from the right side: ### Dossier Contents - **Component Scope & Tier:** Classification and technology stack. - **Architectural Purpose:** Detailed operational responsibilities. - **Inputs & Ingress:** Exact schemas, formats, and network ports consumed. - **Outputs & Egress:** Emitted payloads, status codes, and downstream targets. - **Step-by-Step Workflow:** Ordered lifecycle execution inside the component. - **Key Performance Indicators:** Measurable KPIs and throughput benchmarks. - **Technical Data Contract / Live Code:** Interactive code block displaying validated C# models, TypeScript interfaces, or configuration schemas. - **Verified Source Attribution:** Explicit documentation origin. ### Interactive Actions Inside the Drawer 1. **`View Verified Case Study →`:** Opens the in-depth case study page for that project (e.g. `case-study-ncdot.html`, `case-study-oracle.html`, `case-study-security.html`). 2. **`Copy Technical Contract`:** Copies the exact code snippet / data contract to the system clipboard, providing instant visual confirmation (`✓ Contract Copied!`). 3. **`Run Flow from This Node`:** Starts the workflow simulation beginning at this component. --- ## 8. Navigating the Canvas 1. **Panning:** - Click and drag anywhere on empty canvas space. - Touch drag on mobile or tablet devices. 2. **Zooming:** - Scroll wheel or two-finger trackpad swipe zooms smoothly around the cursor location. - Click `+` or `−` in the bottom-left zoom toolbar. - Zoom level is displayed as a live percentage (`min: 35%`, `max: 220%`). 3. **Fit View (`Fit View` button):** - Automatically calculates the bounding box of all 12 nodes, boundaries, and notes across all 4 domains, centering and framing them with 60px padding and top-bar offset. 4. **Reset Zoom (`100%` button):** - Returns the zoom level to 100% (1.0x scale) while maintaining the current viewport center. 5. **Interactive Minimap:** - Located at the bottom-right corner. - Displays real-time representations of all 12 component cards colored by their cluster. - The semi-transparent camera rectangle outlines the currently visible viewport. - **Clicking anywhere on the minimap** immediately repositions the canvas camera to center on that point. 6. **Dragging Architecture Cards:** - Click and hold any architecture card or sticky note to move it freely across the canvas. - All connected SVG bezier curves and protocol pills dynamically update their endpoints in real-time as nodes are moved! --- ## 9. Keyboard Accessibility & Shortcuts The whiteboard is fully accessible to keyboard-only and assistive technology users: | Key | Action | | :--- | :--- | | **`Space`** | Play or Pause the active workflow simulation. | | **`ArrowRight` (`→`)** | Step forward to the next workflow stage. | | **`ArrowLeft` (`←`)** | Step backward to the previous workflow stage. | | **`Escape` (`Esc`)** | Close open Help Modal, close Detail Drawer, or stop simulation. | | **`Tab` / `Shift + Tab`** | Navigate between top toolbar buttons, architecture cards, and drawer controls in logical focus order. | | **`Enter`** | Activate focused button, or open detail drawer for focused card. | All interactive elements feature high-contrast visible focus rings (`outline: 2px solid #38BDF8; outline-offset: 3px`). --- ## 10. Troubleshooting ### Empty Canvas on Load - **Cause:** Canvas world unpositioned prior to DOM layout calculation. - **Resolution:** The engine now includes static CSS coordinates on every node in `whiteboard.html`, an automated `fitView()` execution on DOMContentLoaded and Window Load, and safe matrix fallbacks. If ever off-screen, click the **`Fit View`** button in the bottom-left toolbar. ### Local Server Returns `ERR_CONNECTION_REFUSED` - **Cause:** No process is listening on port 8089. - **Resolution:** Run `./start_server.sh` from the `complete-portfolio/` directory. Check `.server.log` if port 8089 is occupied by another application. ### Sticky Note Covers Card Content - **Cause:** Coordinate crowding or high z-index. - **Resolution:** Sticky note z-indexes are clamped to 12 (beneath cards at z-index 20). If desired, simply drag the sticky note to any free canvas position. ### Connectors Do Not Update on Drag - **Cause:** Pointer cancellation or focus loss. - **Resolution:** Pointer capture is automatically managed on `pointerdown` and cleared on `pointerup`. Re-clicking the card clears any stale drag state.