COLSYS/geutebruck
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
master
geutebruck/geutebruck-api/docs/README.md
Administrator 14893e62a5 feat: Geutebruck GeViScope/GeViSoft Action Mapping System - MVP 
This MVP release provides a complete full-stack solution for managing action mappings
in Geutebruck's GeViScope and GeViSoft video surveillance systems.

## Features

### Flutter Web Application (Port 8081)
- Modern, responsive UI for managing action mappings
- Action picker dialog with full parameter configuration
- Support for both GSC (GeViScope) and G-Core server actions
- Consistent UI for input and output actions with edit/delete capabilities
- Real-time action mapping creation, editing, and deletion
- Server categorization (GSC: prefix for GeViScope, G-Core: prefix for G-Core servers)

### FastAPI REST Backend (Port 8000)
- RESTful API for action mapping CRUD operations
- Action template service with comprehensive action catalog (247 actions)
- Server management (G-Core and GeViScope servers)
- Configuration tree reading and writing
- JWT authentication with role-based access control
- PostgreSQL database integration

### C# SDK Bridge (gRPC, Port 50051)
- Native integration with GeViSoft SDK (GeViProcAPINET_4_0.dll)
- Action mapping creation with correct binary format
- Support for GSC and G-Core action types
- Proper Camera parameter inclusion in action strings (fixes CrossSwitch bug)
- Action ID lookup table with server-specific action IDs
- Configuration reading/writing via SetupClient

## Bug Fixes
- **CrossSwitch Bug**: GSC and G-Core actions now correctly display camera/PTZ head parameters in GeViSet
- Action strings now include Camera parameter: `@ PanLeft (Comment: "", Camera: 101028)`
- Proper filter flags and VideoInput=0 for action mappings
- Correct action ID assignment (4198 for GSC, 9294 for G-Core PanLeft)

## Technical Stack
- **Frontend**: Flutter Web, Dart, Dio HTTP client
- **Backend**: Python FastAPI, PostgreSQL, Redis
- **SDK Bridge**: C# .NET 8.0, gRPC, GeViSoft SDK
- **Authentication**: JWT tokens
- **Configuration**: GeViSoft .set files (binary format)

## Credentials
- GeViSoft/GeViScope: username=sysadmin, password=masterkey
- Default admin: username=admin, password=admin123

## Deployment
All services run on localhost:
- Flutter Web: http://localhost:8081
- FastAPI: http://localhost:8000
- SDK Bridge gRPC: localhost:50051
- GeViServer: localhost (default port)

Generated with Claude Code (https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
2025-12-31 18:10:54 +01:00

215 lines
6.6 KiB
Markdown
Raw Permalink Blame History

# 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)
Reference in New Issue View Git Blame Copy Permalink