geutebruck/geutebruck-api/docs

Geutebruck API Architecture Documentation

This directory contains comprehensive architecture diagrams and documentation for the Geutebruck API system.

📊 Available Diagrams

PlantUML Diagrams

1. architecture-overview.puml - Complete system architecture

   • Shows all layers (Client, Python API, SDK Bridge, GeViServer)
   • Component relationships and communication
   • Port assignments and protocols
   • Implemented features with status

2. architecture-sequence.puml - Configuration management flow

   • Detailed sequence diagram for creating a G-Core server
   • Shows data flow through all layers
   • Highlights critical implementation details
   • Binary .set file parsing and writing flow

3. architecture-deployment.puml - Deployment view

   • Windows server deployment structure
   • Process relationships (PIDs, ports)
   • Service management scripts
   • Startup order and dependencies

4. architecture-components.puml - Component interactions

   • Detailed component diagram
   • Internal structure of each layer
   • Data models and schemas
   • gRPC protocol definitions
   • Critical bug fixes documentation

Text Diagram

• architecture-text.md - ASCII art architecture diagram
  • Complete system overview in text format
  • Service management details
  • Implemented features checklist

🔧 How to View PlantUML Diagrams

Option 1: VS Code (Recommended)

1. Install the PlantUML extension:

   • Open VS Code
   • Go to Extensions (Ctrl+Shift+X)
   • Search for "PlantUML"
   • Install "PlantUML" by jebbs

2. View diagrams:

   • Open any .puml file
   • Press Alt+D to preview
   • Or right-click → "Preview Current Diagram"

Option 2: Online Viewer

1. Visit PlantUML Online Server
2. Copy the content from any .puml file
3. Paste into the editor
4. View the rendered diagram

Option 3: Export to Image

Using VS Code PlantUML extension:

• Right-click on .puml file
• Select "Export Current Diagram"
• Choose format: PNG, SVG, PDF
• Images will be saved in out/ directory

Option 4: Command Line (Java required)

# Install PlantUML
# Download plantuml.jar from https://plantuml.com/download

# Generate PNG
java -jar plantuml.jar architecture-overview.puml

# Generate SVG
java -jar plantuml.jar -tsvg architecture-overview.puml

# Generate all diagrams
java -jar plantuml.jar *.puml

📋 Diagram Contents

architecture-overview.puml

Visualizes:

• Client Layer: Web browsers, GeViSet, mobile apps, testing tools
• Python API Layer: REST endpoints, services, gRPC client
• C# SDK Bridge: gRPC services, SDK wrappers, configuration handlers
• GeViServer: Camera/monitor management, action engine, binary config storage
• Hardware Layer: IP cameras, monitors, I/O devices

Key Notes:

• Configuration management implementation status ✅
• Data flow for .set file operations
• Current system state (13 servers, 64 mappings)

architecture-sequence.puml

Step-by-step flow for creating a G-Core server:

1. Client sends REST request
2. FastAPI validates and forwards to SDK Bridge
3. SDK Bridge downloads current configuration
4. Parses binary .set file with FolderTreeParser
5. Auto-increments server ID
6. Creates new server node
7. Writes modified tree with FolderTreeWriter
8. Uploads to GeViServer
9. GeViServer saves and reloads configuration
10. Success response returned to client

Critical details documented:

• Bool type handling (type code 1 vs 4)
• Field ordering requirements
• SetupClient port exclusivity

architecture-deployment.puml

Shows actual deployment on Windows Server:

• GeViServer Process (PID: 45612)

  • Binary: GeViServer.exe console
  • Location: C:\GEVISOFT
  • Ports: 7700-7703

• SDK Bridge Process (PID: 48052)

  • Binary: GeViScopeBridge.exe (.NET 8.0)
  • Port: 50051 (gRPC)

• Python API Process (PID: 46212)

  • Runtime: uvicorn + FastAPI
  • Port: 8000 (HTTP)

• PowerShell Scripts: Service lifecycle management

architecture-components.puml

Detailed component breakdown:

• Python API Components:

  • Routers (auth, configuration ✅, cameras, monitors, crossswitch)
  • Services layer
  • gRPC client with proto definitions
  • Pydantic schemas

• C# SDK Bridge Components:

  • gRPC service implementations
  • SDK wrappers (Database, SetupClient ✅, StateQuery)
  • Configuration handlers (Parser ✅, Writer ✅)

• Data Flow:

  • REST → Service → gRPC Client → gRPC Server → SDK → GeViServer
  • Configuration download/parse/modify/serialize/upload cycle

🎯 Implementation Status

✅ Completed Features

1. Configuration Management (User Story 12)

   • G-Core Server CRUD (CREATE, READ, DELETE working)
   • Action Mapping CRUD (all operations working)
   • SetupClient integration
   • FolderTreeParser/Writer for binary .set files
   • Cascade deletion prevention (delete in reverse order)
   • Bool type handling for GeViSet compatibility

2. Service Infrastructure

   • GeViServer startup with "console" argument
   • SDK Bridge gRPC service
   • Python FastAPI REST API
   • Automated service management scripts
   • Port monitoring and health checks

⚠️ Known Issues

1. Server UPDATE Method

   • Error: "Server ID is required"
   • Workaround: Delete and recreate
   • Status: Documented, fix pending

2. SetupClient Port Conflict

   • GeViSet and SDK Bridge cannot both connect
   • Workaround: Stop SDK Bridge when using GeViSet
   • Status: Design limitation

📚 Additional Documentation

• SERVER_CRUD_IMPLEMENTATION.md - Implementation guide
• CRITICAL_BUG_FIX_DELETE.md - Cascade deletion bug analysis
• specs/001-surveillance-api/ - Complete specifications

🔄 Updates

• 2025-12-16: Added PlantUML diagrams for architecture visualization
• 2025-12-16: Documented configuration management implementation
• 2025-12-16: Fixed Python import errors in proto files

🤝 Contributing

When updating diagrams:

1. Edit the .puml source files
2. Regenerate images if needed
3. Update this README if adding new diagrams
4. Commit both source and generated images

📖 References

• PlantUML Documentation
• PlantUML Component Diagrams
• PlantUML Sequence Diagrams
• PlantUML Deployment Diagrams