# 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](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](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](architecture-deployment.puml)** - Deployment view
   - Windows server deployment structure
   - Process relationships (PIDs, ports)
   - Service management scripts
   - Startup order and dependencies

4. **[architecture-components.puml](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](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](http://www.plantuml.com/plantuml/uml/)
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)

```bash
# 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](../SERVER_CRUD_IMPLEMENTATION.md) - Implementation guide
- [CRITICAL_BUG_FIX_DELETE.md](../CRITICAL_BUG_FIX_DELETE.md) - Cascade deletion bug analysis
- [specs/001-surveillance-api/](../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](https://plantuml.com/)
- [PlantUML Component Diagrams](https://plantuml.com/component-diagram)
- [PlantUML Sequence Diagrams](https://plantuml.com/sequence-diagram)
- [PlantUML Deployment Diagrams](https://plantuml.com/deployment-diagram)