resolutionflow/02-TECHNICAL-ARCHITECTURE.md

Technical Architecture

System Architecture

High-Level Architecture

┌─────────────────────────────────────────────────────┐
│                  Frontend (React/Vue)                │
│  - Tree Navigation UI                               │
│  - Tree Editor                                      │
│  - Session Management                               │
│  - Export Functionality                             │
└─────────────────┬───────────────────────────────────┘
                  │ REST API / WebSocket
┌─────────────────┴───────────────────────────────────┐
│              Backend (Python Flask/FastAPI)          │
│  - Authentication & Authorization                   │
│  - Tree CRUD Operations                             │
│  - Session Tracking                                 │
│  - Export Generation                                │
│  - File Upload/Storage                              │
│  - Automation Execution (Future)                    │
└─────────────────┬───────────────────────────────────┘
                  │
┌─────────────────┴───────────────────────────────────┐
│              Database (PostgreSQL)                   │
│  - Trees (JSON)                                     │
│  - Sessions                                         │
│  - Users & Teams                                    │
│  - Attachments Metadata                             │
└──────────────────────────────────────────────────────┘
                  │
┌─────────────────┴───────────────────────────────────┐
│           Object Storage (S3/MinIO)                  │
│  - Screenshots                                      │
│  - Command Outputs                                  │
│  - Logs & Attachments                               │
└──────────────────────────────────────────────────────┘

Tech Stack

Frontend

Primary Choice: React

• Pros: Large ecosystem, excellent offline support (PWA), familiar to most developers
• Alternatives: Vue.js (simpler), Svelte (faster)
• UI Framework: Tailwind CSS + shadcn/ui (clean, professional look)
• State Management: React Context + useReducer (simple) or Zustand (if needed)
• Routing: React Router
• Offline: Service Workers + IndexedDB for offline tree caching

Backend

Primary Choice: Python FastAPI

• Pros: Modern, fast, async support, automatic API docs, matches Michael's learning path
• Alternatives: Flask (simpler but less performant), Django (heavier)
• Authentication: JWT tokens + httpOnly cookies
• Validation: Pydantic models
• ORM: SQLAlchemy 2.0 (async)
• Migration: Alembic

Database

Primary Choice: PostgreSQL

• Pros: JSON/JSONB support perfect for tree storage, reliable, scalable
• Schema Design:
  • Hybrid approach: Relational for users/sessions, JSONB for tree structure
  • Full-text search for tree discovery
  • Indexes on frequently queried fields

File Storage

Primary Choice: S3-compatible storage

• Development: MinIO (self-hosted, S3-compatible)
• Production: AWS S3 or DigitalOcean Spaces
• Strategy: Pre-signed URLs for uploads, CDN for delivery

Hosting

Development:

• Frontend: Local dev server (Vite)
• Backend: Local Python server
• Database: Docker PostgreSQL

Production Options:

1. Simple Start: Railway or Render (full-stack hosting)

   • Cost: ~$10-20/month
   • Pros: Easy deployment, managed databases
   • Cons: Less control, potential scaling issues

2. Scalable: DigitalOcean Droplets + Managed DB

   • Cost: ~$30-50/month
   • Pros: More control, better performance
   • Cons: More maintenance

3. Enterprise: AWS/Azure

   • Cost: Variable
   • Pros: Full feature set, enterprise compliance
   • Cons: Complex, expensive

Data Models

Database Schema

Users Table

CREATE TABLE users (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash VARCHAR(255) NOT NULL,
    name VARCHAR(255) NOT NULL,
    role VARCHAR(50) NOT NULL, -- admin, engineer, viewer
    team_id UUID REFERENCES teams(id),
    created_at TIMESTAMP DEFAULT NOW(),
    last_login TIMESTAMP
);

Teams Table

CREATE TABLE teams (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    created_at TIMESTAMP DEFAULT NOW()
);

Trees Table

CREATE TABLE trees (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    name VARCHAR(255) NOT NULL,
    description TEXT,
    category VARCHAR(100), -- Citrix, Active Directory, Networking, etc.
    tree_structure JSONB NOT NULL, -- The actual decision tree
    author_id UUID REFERENCES users(id),
    team_id UUID REFERENCES teams(id),
    is_active BOOLEAN DEFAULT true,
    version INTEGER DEFAULT 1,
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW(),
    usage_count INTEGER DEFAULT 0
);

CREATE INDEX idx_trees_category ON trees(category);
CREATE INDEX idx_trees_team ON trees(team_id);
CREATE INDEX idx_trees_search ON trees USING gin(to_tsvector('english', name || ' ' || description));

Sessions Table

CREATE TABLE sessions (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    tree_id UUID REFERENCES trees(id),
    user_id UUID REFERENCES users(id),
    tree_snapshot JSONB NOT NULL, -- Copy of tree at time of use (for version tracking)
    path_taken JSONB NOT NULL, -- Array of node_ids visited
    decisions JSONB NOT NULL, -- Decisions made at each node with notes
    started_at TIMESTAMP DEFAULT NOW(),
    completed_at TIMESTAMP,
    ticket_number VARCHAR(100),
    client_name VARCHAR(255),
    exported BOOLEAN DEFAULT false
);

CREATE INDEX idx_sessions_user ON sessions(user_id);
CREATE INDEX idx_sessions_tree ON sessions(tree_id);
CREATE INDEX idx_sessions_dates ON sessions(started_at, completed_at);

Attachments Table

CREATE TABLE attachments (
    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
    session_id UUID REFERENCES sessions(id),
    node_id VARCHAR(100), -- Which decision node this was attached to
    file_name VARCHAR(255) NOT NULL,
    file_type VARCHAR(50),
    file_size INTEGER,
    storage_path VARCHAR(500), -- S3 key or file path
    uploaded_at TIMESTAMP DEFAULT NOW()
);

Tree Structure (JSON)

{
  "tree_id": "citrix-vda-not-registering",
  "name": "Citrix VDA Not Registering",
  "category": "Citrix",
  "description": "Troubleshoot VDA registration issues with Delivery Controller",
  "estimated_time": "10-15 minutes",
  "start_node": "node_1",
  "metadata": {
    "author": "Michael Chihlas",
    "created": "2026-01-22",
    "last_updated": "2026-01-22",
    "version": "1.0",
    "tags": ["citrix", "vda", "registration", "delivery-controller"]
  },
  "nodes": {
    "node_1": {
      "id": "node_1",
      "type": "decision",
      "question": "Can you ping the VDA from the Delivery Controller?",
      "help_text": "From DDC, open PowerShell and run: Test-Connection -ComputerName VDA-HOSTNAME -Count 4",
      "documentation_links": [
        {
          "title": "Citrix VDA Communication Requirements",
          "url": "https://docs.citrix.com/..."
        }
      ],
      "decision_type": "yes_no",
      "allow_notes": true,
      "allow_attachments": true,
      "allow_custom_branch": true,
      "yes": "node_2",
      "no": "node_network_issue"
    },
    "node_2": {
      "id": "node_2",
      "type": "decision",
      "question": "What is the status of the Citrix Virtual Desktop Agent service?",
      "help_text": "Run: Get-Service -Name 'BrokerAgent' | Select-Object Status, StartType",
      "decision_type": "multiple_choice",
      "allow_notes": true,
      "options": [
        {
          "label": "Running",
          "value": "running",
          "next": "node_check_broker"
        },
        {
          "label": "Stopped",
          "value": "stopped",
          "next": "node_start_service"
        },
        {
          "label": "Stuck in Starting/Stopping",
          "value": "stuck",
          "next": "node_service_stuck"
        }
      ]
    },
    "node_check_broker": {
      "id": "node_check_broker",
      "type": "action",
      "title": "Check Broker Connection",
      "instruction": "Verify the VDA can communicate with the Delivery Controller on port 80/443",
      "commands": [
        "Test-NetConnection -ComputerName DDC-HOSTNAME -Port 80",
        "Test-NetConnection -ComputerName DDC-HOSTNAME -Port 443"
      ],
      "documentation_links": [
        {
          "title": "VDA to DDC Communication Ports",
          "url": "https://docs.citrix.com/..."
        }
      ],
      "automation_available": false,
      "next": "node_3"
    },
    "node_start_service": {
      "id": "node_start_service",
      "type": "action",
      "title": "Start Citrix VDA Service",
      "instruction": "Start the Citrix Virtual Desktop Agent service and check for errors",
      "commands": [
        "Start-Service -Name 'BrokerAgent'",
        "Get-Service -Name 'BrokerAgent' | Select-Object Status"
      ],
      "automation_available": true,
      "automation": {
        "type": "powershell",
        "script_id": "start-citrix-vda-service",
        "description": "Starts Citrix VDA service with error handling",
        "requires_elevation": true,
        "parameters": []
      },
      "next": "node_verify_registration"
    },
    "node_verify_registration": {
      "id": "node_verify_registration",
      "type": "decision",
      "question": "Is the VDA now showing as registered in Citrix Studio?",
      "help_text": "Open Citrix Studio > Machine Catalogs > Check VDA status",
      "decision_type": "yes_no",
      "yes": "node_resolved",
      "no": "node_check_event_viewer"
    },
    "node_resolved": {
      "id": "node_resolved",
      "type": "resolution",
      "title": "Issue Resolved",
      "summary": "VDA successfully registered with Delivery Controller",
      "resolution_notes": "Document the specific action that resolved the issue in the notes above."
    },
    "node_network_issue": {
      "id": "node_network_issue",
      "type": "branch",
      "title": "Network Connectivity Issue Detected",
      "description": "Unable to ping VDA from DDC - this is a network/firewall issue",
      "suggested_next_tree": "network-connectivity-troubleshooting",
      "manual_steps": [
        "Check if VDA is powered on",
        "Verify network cable is connected",
        "Check firewall rules between DDC and VDA",
        "Verify DNS resolution for VDA hostname"
      ]
    }
  }
}

Session Data Structure

{
  "session_id": "abc-123",
  "tree_id": "citrix-vda-not-registering",
  "tree_snapshot": { /* full tree at time of use */ },
  "user_id": "user-456",
  "started_at": "2026-01-22T14:30:00Z",
  "completed_at": "2026-01-22T14:45:00Z",
  "ticket_number": "INC-12345",
  "client_name": "City of Warner Robins",
  "path_taken": [
    "node_1",
    "node_2", 
    "node_start_service",
    "node_verify_registration",
    "node_resolved"
  ],
  "decisions": [
    {
      "node_id": "node_1",
      "question": "Can you ping the VDA from the Delivery Controller?",
      "answer": "yes",
      "notes": "Ping successful, 2ms response time, no packet loss",
      "timestamp": "2026-01-22T14:31:00Z",
      "attachments": []
    },
    {
      "node_id": "node_2",
      "question": "What is the status of the Citrix Virtual Desktop Agent service?",
      "answer": "stopped",
      "notes": "Service was stopped. Checking dependencies - NetLogon service also stopped.",
      "timestamp": "2026-01-22T14:33:00Z",
      "attachments": ["attachment-id-789"]
    },
    {
      "node_id": "node_start_service",
      "action_performed": "Started Citrix VDA service",
      "notes": "Started NetLogon first, then BrokerAgent. Both services now running.",
      "automation_used": false,
      "timestamp": "2026-01-22T14:40:00Z",
      "attachments": []
    },
    {
      "node_id": "node_verify_registration",
      "question": "Is the VDA now showing as registered in Citrix Studio?",
      "answer": "yes",
      "notes": "VDA shows as 'Registered' in Studio. User able to launch session successfully.",
      "timestamp": "2026-01-22T14:44:00Z",
      "attachments": ["screenshot-registration.png"]
    }
  ]
}

API Endpoints

Authentication

POST   /api/auth/register       - Register new user
POST   /api/auth/login          - Login
POST   /api/auth/logout         - Logout
GET    /api/auth/me             - Get current user
POST   /api/auth/refresh        - Refresh JWT token

Trees

GET    /api/trees               - List all trees (with filters)
GET    /api/trees/:id           - Get specific tree
POST   /api/trees               - Create new tree (admin/engineer only)
PUT    /api/trees/:id           - Update tree (admin/engineer only)
DELETE /api/trees/:id           - Soft delete tree (admin only)
GET    /api/trees/categories    - List all categories
GET    /api/trees/search        - Full-text search trees

Sessions

GET    /api/sessions            - List user's sessions
GET    /api/sessions/:id        - Get specific session
POST   /api/sessions            - Start new troubleshooting session
PUT    /api/sessions/:id        - Update session (add decisions/notes)
POST   /api/sessions/:id/complete - Mark session as complete
POST   /api/sessions/:id/export - Export session to formatted notes

Attachments

POST   /api/sessions/:id/attachments       - Upload attachment
GET    /api/sessions/:id/attachments       - List attachments
GET    /api/attachments/:id                - Get attachment
DELETE /api/attachments/:id                - Delete attachment

Teams (Phase 2)

GET    /api/teams                - List teams
POST   /api/teams                - Create team (admin only)
GET    /api/teams/:id/members    - List team members
POST   /api/teams/:id/members    - Add team member
DELETE /api/teams/:id/members/:user_id - Remove team member

Analytics (Phase 3)

GET    /api/analytics/trees/:id/usage      - Tree usage statistics
GET    /api/analytics/trees/:id/paths      - Common paths taken
GET    /api/analytics/team/performance     - Team troubleshooting metrics
GET    /api/analytics/user/history         - User's troubleshooting history

Automation (Phase 4)

GET    /api/automation/scripts              - List available automation scripts
POST   /api/automation/execute              - Execute automation script
GET    /api/automation/history              - Automation execution history

Security Considerations

Authentication & Authorization

• JWT tokens with short expiry (15 min access, 7 day refresh)
• Role-based access control (RBAC)
• Password requirements: min 10 chars, complexity
• Rate limiting on auth endpoints
• Account lockout after failed attempts

Data Protection

• All passwords hashed with bcrypt (cost factor 12)
• Sensitive data encrypted at rest
• HTTPS only in production
• CORS properly configured
• SQL injection prevention (parameterized queries)
• XSS prevention (input sanitization, CSP headers)

File Upload Security

• File type validation (whitelist only)
• File size limits (10MB per file)
• Virus scanning (ClamAV integration for Phase 3)
• Separate storage domain (prevent XSS via uploads)
• Signed URLs with expiration

API Security

• Rate limiting (100 requests/min per user)
• Request size limits
• API versioning (/api/v1/...)
• Audit logging for sensitive operations

Performance Considerations

Database

• Indexes on frequently queried fields
• Connection pooling
• Query optimization (EXPLAIN ANALYZE)
• Consider read replicas for Phase 3+

Caching Strategy

• Redis for session storage (Phase 2)
• Cache frequently accessed trees
• CDN for static assets
• Browser caching headers

Frontend Performance

• Code splitting (lazy load routes)
• Tree data cached in IndexedDB
• Debounced search inputs
• Virtualized lists for large datasets
• Optimistic UI updates

Monitoring & Observability

Logging

• Structured logging (JSON format)
• Log levels: DEBUG, INFO, WARNING, ERROR, CRITICAL
• Request ID tracking across services
• User action auditing

Metrics (Phase 3)

• API response times
• Database query performance
• Error rates
• User engagement metrics
• System resource usage

Error Tracking

• Sentry integration for error tracking
• User-friendly error messages
• Automatic error reporting with context

Deployment Strategy

CI/CD Pipeline

1. Development: Local development with hot reload
2. Testing: Automated tests on PR
3. Staging: Auto-deploy to staging environment
4. Production: Manual approval → deploy

Database Migrations

• Alembic for schema migrations
• Backwards-compatible changes
• Rollback capability
• Test migrations on staging first

Backup Strategy

• Automated daily database backups
• Point-in-time recovery capability
• File storage replication
• Backup retention: 30 days

Future Technical Considerations

Scalability

• Horizontal scaling (multiple app servers)
• Database sharding (by team_id)
• Microservices architecture (if needed)
• Message queue for async tasks (Celery + Redis)

Mobile Apps

• React Native for iOS/Android
• Shared API backend
• Offline-first architecture
• Push notifications for team updates

AI/ML Integration (Phase 5+)

• Suggest next steps based on past sessions
• Auto-categorize tickets
• Predict resolution time
• Natural language tree navigation