COPILOT/Docs/plans/PHASE_0_INFRASTRUCTURE.md

Phase 0: Infrastructure Implementation Plan

Status: In Progress Duration: Week 1-2 Goal: Finalize bridges, add event subscriptions, test direct commands, document configurations

---

Current State Assessment

Bridge Readiness

Bridge	Port	Status	PLC Events	ViewerConnectLive	PTZ	Playback
GeViScope	7720	✅ Ready	✅	✅	✅	✅
G-Core	7721	✅ Ready	✅	✅	✅	✅
GeViServer	7710	⚠️ Minimal	⚠️ Events only	❌	❌	❌

Decision: GeViServer Bridge remains minimal per design ("Minimal GeViSoft usage").

---

Phase 0 Tasks

Task 1: Event Notification Forwarding ✅ COMPLETED

Priority: HIGH Effort: 4-6 hours Status: Done (2026-02-03)

The bridges have PLC subscriptions but notifications are only logged. For the new architecture, events must be forwarded to the Flutter app.

Sub-tasks:

1. Add WebSocket endpoint to GeViScope Bridge for event streaming (ws://localhost:7720/ws/events)
2. Add WebSocket endpoint to G-Core Bridge for event streaming (ws://localhost:7721/ws/events)
3. Define event message format (JSON)
4. Forward these events:
   • ViewerConnected(Viewer, Channel, PlayMode)
   • ViewerCleared(Viewer)
   • ViewerSelectionChanged(Viewer, Channel, PlayMode)
   • EventStarted(EventID, TypeID, ForeignKey)
   • EventStopped(EventID, TypeID)
   • VCAlarmQueueNotification(Viewer, Notification, AlarmID, TypeID)
   • DigitalInput(Contact, State)
   • ConnectionLost (bonus)

Event Message Format:

{
  "timestamp": "2026-02-03T10:30:00.123Z",
  "server": "GeViScope-01",
  "action": "ViewerConnected",
  "params": {
    "Viewer": 5,
    "Channel": 101,
    "PlayMode": 11
  }
}

---

Task 2: Alarm Query Endpoints ✅ COMPLETED (Event-Based)

Priority: HIGH Effort: 3-4 hours Status: Done (2026-02-03)

Add alarm query capability to bridges (critical for "never miss alarms" requirement).

Finding: GeViScope/G-Core SDKs don't have direct alarm query APIs like GeViSoft. They use event-based tracking.

Implementation:

• Research GeViScope SDK - uses EventStarted/EventStopped notifications (no query API)
• Research G-Core SDK - uses EventStarted/EventStopped notifications (no query API)
• Implement GET /alarms/active - returns alarms tracked from events
• Implement GET /alarms - returns all tracked alarms (active + stopped)
• Track alarm state from EventStarted/EventStopped notifications

Important: For complete alarm state on startup (before any events received), the Flutter app should query GeViServer bridge which has GeViSQ_GetFirstAlarm/GetNextAlarm methods.

---

Task 3: Monitor State Query ✅ COMPLETED (Event-Based)

Priority: MEDIUM Effort: 2-3 hours Status: Done (2026-02-03)

Add ability to query current monitor state on startup.

Finding: GeViScope/G-Core SDKs use ViewerConnected/ViewerCleared events for state changes. GetFirstVideoOutput is GeViSoft SDK only.

Implementation:

• Research GeViScope SDK - uses ViewerConnected/ViewerCleared/ViewerSelectionChanged events
• Research G-Core SDK - same event-based approach
• Implement GET /monitors - returns all monitored states tracked from events
• Implement GET /monitors/{viewerId} - returns specific monitor state
• Track monitor state from ViewerConnected/ViewerCleared events

Important: For complete monitor state on startup (before any events received), the Flutter app should either:

1. Trigger a ViewerConnectLive to each known monitor (will fire ViewerConnected event)
2. Query GeViServer bridge if GeViSoft integration is acceptable

---

Task 4: Server Configuration Documentation ✅ COMPLETED

Priority: MEDIUM Effort: 2-3 hours Status: Done (2026-02-03)

Document server configurations for deployment.

Sub-tasks:

1. Create servers.json template with all server definitions
2. Document camera ID ranges per server
3. Document monitor ID mappings
4. Create crossswitch-rules.json template
5. Create keyboards.json template

Files Created:

• C:\DEV\COPILOT_D6\config\servers.json.template
• C:\DEV\COPILOT_D6\config\crossswitch-rules.json.template
• C:\DEV\COPILOT_D6\config\keyboards.json.template

---

Task 5: Bridge Health Checks ✅ COMPLETED

Priority: MEDIUM Effort: 1-2 hours Status: Done (2026-02-03)

Enhance health check endpoints for production monitoring.

Sub-tasks:

1. Add detailed status to /status endpoint:
   • is_connected (bool)
   • address (server address)
   • connection_duration_sec
   • event_count (since connection)
   • websocket_clients (connected WS clients)
   • plc_active (bool)
2. Add /health endpoint for load balancer probes
3. Add connection auto-reconnect logic (deferred to Phase 1)

---

Task 6: Integration Testing ⬜ IN PROGRESS

Priority: HIGH Effort: 4-6 hours

Test bridges against actual servers.

Sub-tasks:

1. Test GeViScope Bridge against real GeViScope server
   • Connection/disconnection
   • ViewerConnectLive
   • PTZ control
   • Event reception via WebSocket
2. Test G-Core Bridge against real G-Core server
   • Same tests as above
3. Create test scripts (HTTP files)
   • C:\DEV\COPILOT_D6\tests\test-geviscope.http
   • C:\DEV\COPILOT_D6\tests\test-gcore.http
4. Document any SDK issues found

---

Task 7: Logging Standardization ⬜

Priority: LOW Effort: 2 hours

Standardize logging format for Kibana integration.

Sub-tasks:

1. Configure Serilog with JSON formatter
2. Add structured logging fields:
   • keyboard_id
   • server_id
   • command
   • duration_ms
   • success
3. Configure log rotation
4. Test log output format

---

File Structure After Phase 0

C:\DEV\COPILOT_D6\
├── docs\
│   ├── NEW_SYSTEM_DESIGN_SUMMARY.md
│   ├── IMPLEMENTATION_QUICK_REFERENCE.md
│   └── plans\
│       └── PHASE_0_INFRASTRUCTURE.md
├── config\
│   ├── servers.json.template        ✅ Created
│   ├── crossswitch-rules.json.template  ✅ Created
│   └── keyboards.json.template      ✅ Created
└── tests\
    ├── test-geviscope.http          ✅ Created
    └── test-gcore.http              ✅ Created

Bridges (existing, enhanced):
├── C:\DEV\COPILOT\geviscope-bridge\  ✅ WebSocket added
└── C:\DEV\COPILOT\gcore-bridge\      ✅ WebSocket added

---

Success Criteria

• Events are streamed via WebSocket from both bridges
• Alarm state can be queried on demand (event-based tracking + /alarms/active endpoint)
• Monitor state can be queried on demand (event-based tracking + /monitors endpoint)
• Configuration templates are documented
• All bridge endpoints tested against real servers
• Logging format matches ELK requirements (Task 7 - pending, low priority)

---

Dependencies

• Access to GeViScope server for testing
• Access to G-Core server for testing
• GeViScope SDK documentation (chunk files available)
• G-Core SDK documentation (chunk files available)

---

Next Phase

After Phase 0, proceed to Phase 1: Flutter Keyboard Core

• Keyboard layout UI
• Direct command execution
• Server routing logic
• State notification subscription