geutebruck/geutebruck-api/docs/architecture-components.puml

@startuml Component Interactions
!theme plain
skinparam backgroundColor #FEFEFE

title Geutebruck API - Component Interactions & Data Flow

package "Python API (Port 8000)" {

    [main.py\nFastAPI App] as main

    package "Routers" {
        [auth.py] as authrouter
        [configuration.py\n✅ IMPLEMENTED] as configrouter
        [cameras.py] as camrouter
        [monitors.py] as monrouter
        [crossswitch.py] as crossrouter
    }

    package "Services" {
        [configuration_service.py\n✅ IMPLEMENTED] as configsvc
        [camera_service.py] as camsvc
        [monitor_service.py] as monsvc
        [crossswitch_service.py] as crosssvc
    }

    package "Clients" {
        [sdk_bridge_client.py\ngRPC Client] as grpcclient
    }

    package "Schemas (Pydantic)" {
        [GCoreServer\nGCoreServerInput] as serverschema
        [ActionMapping\nActionMappingInput] as mappingschema
        [Camera, Monitor] as schemas
    }

    package "Proto (gRPC Generated)" {
        [configuration_pb2.py\nconfiguration_pb2_grpc.py\n✅ FIXED IMPORTS] as configproto
        [camera_pb2.py\nmonitor_pb2.py] as otherproto
    }
}

package "C# SDK Bridge (Port 50051)" {

    [Program.cs\ngRPC Server] as program

    package "Services (gRPC)" {
        [ConfigurationService.cs\n✅ IMPLEMENTED] as configgrpc
        [CameraService.cs] as camgrpc
        [MonitorService.cs] as mongrpc
        [CrossSwitchService.cs] as crossgrpc
    }

    package "SDK Wrappers" {
        [GeViDatabaseWrapper.cs] as dbwrapper
        [GeViSetupClientWrapper.cs\n✅ IMPLEMENTED] as setupwrapper
        [StateQueryHandler.cs] as statehandler
        [ActionDispatcher.cs] as dispatcher
    }

    package "Configuration Handlers" {
        [FolderTreeParser.cs\n✅ IMPLEMENTED] as parser
        [FolderTreeWriter.cs\n✅ IMPLEMENTED] as writer
    }

    package "Proto (gRPC Generated)" {
        [configuration.proto\nConfigurationService] as configdef
        [camera.proto\nmonitor.proto] as otherdef
    }
}

package "GeViServer (Ports 7700-7703)" {

    [GeViServer.exe] as geviserver

    package "SDK API (C++ DLL)" {
        [GeViProcAPINET_4_0.dll\nGeViScope SDK] as sdk
    }

    package "Configuration" {
        database "TestMKS.set\n(Binary)" as config {
            folder "GeViGCoreServer" as serversfolder {
                [Server_1\nServer_2\n...\nServer_13] as servers
            }
            folder "ActionMapping" as mappingfolder {
                [Mapping rules\n64 entries] as mappings
            }
        }
    }
}

' Python API Internal Flow
main --> authrouter
main --> configrouter
main --> camrouter

configrouter --> configsvc : Uses
configsvc --> serverschema : Validates
configsvc --> mappingschema : Validates
configsvc --> grpcclient : Calls

grpcclient --> configproto : Uses

' Python to C# Communication
configproto ..> configdef : gRPC\nPort 50051
otherproto ..> otherdef : gRPC

' C# SDK Bridge Internal Flow
program --> configgrpc : Hosts
program --> camgrpc : Hosts

configgrpc --> setupwrapper : Uses
setupwrapper --> parser : Downloads &\nparses config
setupwrapper --> writer : Builds &\nuploads config

camgrpc --> dbwrapper : Uses
camgrpc --> statehandler : Uses

' C# to GeViServer Communication
dbwrapper --> sdk : Calls\nSDK API
setupwrapper --> sdk : SetupClient\nprotocol
statehandler --> sdk : Query API

sdk --> geviserver : Ports\n7700-7703

geviserver --> config : Read/Write

note right of configrouter
  **REST Endpoints:**

  GET    /api/v1/configuration/servers
  POST   /api/v1/configuration/servers
  PUT    /api/v1/configuration/servers/{id}
  DELETE /api/v1/configuration/servers/{id}

  GET    /api/v1/configuration/action-mappings
  POST   /api/v1/configuration/action-mappings
  PUT    /api/v1/configuration/action-mappings/{id}
  DELETE /api/v1/configuration/action-mappings/{id}
end note

note right of configgrpc
  **gRPC Methods:**

  CreateServer(ServerRequest)
  GetAllServers(Empty)
  GetServer(ServerIdRequest)
  UpdateServer(ServerRequest) ⚠️
  DeleteServer(ServerIdRequest)

  CreateActionMapping(MappingRequest)
  GetAllActionMappings(Empty)
  GetActionMapping(MappingIdRequest)
  UpdateActionMapping(MappingRequest)
  DeleteActionMapping(MappingIdRequest)

  ReadConfigurationTree(Empty)
end note

note right of parser
  **FolderTreeParser:**

  1. Receives binary .set file
  2. Parses header and structure
  3. Builds tree of FolderNode objects
  4. Each node has:
     - Name, Type, Value
     - Children (recursive)
  5. Returns navigable tree
end note

note right of writer
  **FolderTreeWriter:**

  1. Takes FolderNode tree
  2. Validates structure
  3. Serializes to binary format:
     - Type codes (1=bool, 4=int32, etc)
     - String lengths
     - Nested structures
  4. Returns binary .set data
  5. Uploaded via SetupClient
end note

note bottom of config
  **Binary Configuration:**

  • Proprietary GeViSoft format
  • Hierarchical folder/node structure
  • Type-safe fields with type codes
  • Critical: bool vs int32 type handling
  • Must preserve field order
  • Auto-save on change
end note

note as criticalfix
  **Critical Bug Fix (2025-12-16):**

  **Cascade Deletion Prevention**
  - Problem: Deleting mappings by ID in ascending
    order caused ID shifting, deleting wrong items
  - Solution: Always delete in REVERSE order
    (highest ID first)
  - Impact: Prevented loss of ~54 mappings
  - Status: FIXED in comprehensive_crud_test.py
end note

@enduml