# opencop-oss/opencop architecture

> Architecture diagram of the GitHub repository opencop-oss/opencop, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-09). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/opencop-oss/opencop
- Repository: https://github.com/opencop-oss/opencop

## Overview

OpenCOP is a web-based common operating picture: users connect live feeds or publish BYOD records, map incoming fields into geographic features, and view shared operational data on a map. The repository also includes access-controlled layers and sources, real-time event delivery, historical event and track workflows, watchbox processing, and plugin-based map rendering. The graph preserves these documented product branches; several backend and frontend paths are represented at their enclosing directories because their implementation files were not sampled.

Main entry points: [`frontend/packages/app/src/features/map`](https://github.com/opencop-oss/opencop/tree/main/frontend/packages/app/src/features/map) (Operational map), [`backend/processor/src/main/java/com/opencop/processor/technical/gateway/db/PostGisService.java`](https://github.com/opencop-oss/opencop/blob/main/backend/processor/src/main/java/com/opencop/processor/technical/gateway/db/PostGisService.java) (Geographic features), [`backend/core/src/main/java/com/opencop/core/api/general/technical/service/SourceRelationshipAuthorizationService.java`](https://github.com/opencop-oss/opencop/blob/main/backend/core/src/main/java/com/opencop/core/api/general/technical/service/SourceRelationshipAuthorizationService.java) (Layer access), [`backend/sdk/src/main/java/com/opencop/core/sdk/ports/gateway/mapper/MapperProfileService.java`](https://github.com/opencop-oss/opencop/blob/main/backend/sdk/src/main/java/com/opencop/core/sdk/ports/gateway/mapper/MapperProfileService.java) (Field mapping)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_integration["Data integration"]
  node_connect["Socket lifecycle"]
  node_connection_manager["Connection manager"]
  node_socket_connectors["TCP UDP RTSP"]
  node_byod["Kafka BYOD"]
  node_mapper["Field mapping"]
end

subgraph group_processing["Processing and history"]
  node_feature_store[("Geographic features")]
  node_event_api["Event history API"]
  node_historical_tracks["Historical tracks"]
  node_watchbox["Watchbox transitions"]
end

subgraph group_services["Core services"]
  node_authorization["Layer access"]
  node_layer_directory[("Layer directory")]
  node_user_directory[("User directory")]
end

subgraph group_realtime["Realtime delivery"]
  node_websocket["WebSocket events"]
end

subgraph group_client["Web map"]
  node_webapp["Web application"]
  node_map["Operational map"]
  node_render["Render pipeline<br/>[RenderPipeline.ts]"]
  node_session["Session rendering<br/>[SessionPipeline.ts]"]
  node_plugins["Plugin tools<br/>[PluginManager.ts]"]
  node_weather["Weather overlays"]
end

node_operator(("Operator"))
node_source(("External sources"))

node_operator -->|"uses"| node_webapp
node_source -->|"provides feed"| node_connect
node_source -->|"publishes records"| node_byod
node_connect -->|"manages lifecycle"| node_connection_manager
node_connection_manager -.->|"starts connectors"| node_socket_connectors
node_byod -->|"maps fields"| node_mapper
node_socket_connectors -->|"maps fields"| node_mapper
node_mapper -->|"creates features"| node_feature_store
node_feature_store -->|"feeds picture"| node_map
node_operator -->|"configures sources"| node_webapp
node_webapp -->|"explores"| node_map
node_map -.->|"renders scene"| node_render
node_render -->|"uses pipeline"| node_session
node_plugins -->|"extends tools"| node_map
node_map -->|"shows overlays"| node_weather
node_map -->|"inspects history"| node_event_api
node_map -->|"replays movement"| node_historical_tracks
node_event_api -.->|"delivers events"| node_websocket
node_websocket -.->|"streams updates"| node_map
node_feature_store -.->|"evaluates observations"| node_watchbox
node_operator -->|"requests access"| node_authorization
node_authorization -.->|"checks layers"| node_layer_directory
node_authorization -.->|"checks users"| node_user_directory

click node_webapp "https://github.com/opencop-oss/opencop/tree/main/frontend/packages/app/src"
click node_map "https://github.com/opencop-oss/opencop/tree/main/frontend/packages/app/src/features/map"
click node_render "https://github.com/opencop-oss/opencop/blob/main/frontend/packages/app/src/features/map/scene-binding/RenderPipeline.ts"
click node_session "https://github.com/opencop-oss/opencop/blob/main/frontend/packages/app/src/features/map/scene-binding/session/SessionPipeline.ts"
click node_plugins "https://github.com/opencop-oss/opencop/blob/main/frontend/packages/contributions/src/host/PluginManager.ts"
click node_connect "https://github.com/opencop-oss/opencop/blob/main/backend/connect/src/main/java/com/opencop/api/connect/business/connector/ConnectionLifecycleService.java"
click node_connection_manager "https://github.com/opencop-oss/opencop/blob/main/backend/connect/src/main/java/com/opencop/api/connect/business/connector/ConnectionManager.java"
click node_socket_connectors "https://github.com/opencop-oss/opencop/tree/main/backend/connect/src/main/java/com/opencop/api/connect/technical/gateway/socket"
click node_byod "https://github.com/opencop-oss/opencop/tree/main/backend/processor/src/main/java/com/opencop/processor/technical/spring/config/byod"
click node_mapper "https://github.com/opencop-oss/opencop/blob/main/backend/sdk/src/main/java/com/opencop/core/sdk/ports/gateway/mapper/MapperProfileService.java"
click node_feature_store "https://github.com/opencop-oss/opencop/blob/main/backend/processor/src/main/java/com/opencop/processor/technical/gateway/db/PostGisService.java"
click node_event_api "https://github.com/opencop-oss/opencop/tree/main/backend/core/src/main/java/com/opencop/core/api/event"
click node_historical_tracks "https://github.com/opencop-oss/opencop/tree/main/backend/processor/src/main/java/com/opencop/processor/business/usecase/history"
click node_watchbox "https://github.com/opencop-oss/opencop/blob/main/backend/processor/src/main/java/com/opencop/processor/business/usecase/watchbox/WatchboxTransitionEngine.java"
click node_authorization "https://github.com/opencop-oss/opencop/blob/main/backend/core/src/main/java/com/opencop/core/api/general/technical/service/SourceRelationshipAuthorizationService.java"
click node_layer_directory "https://github.com/opencop-oss/opencop/blob/main/backend/core/src/main/java/com/opencop/core/api/iam/technical/gateway/db/layers/directory/LayerDirectoryQueryService.java"
click node_user_directory "https://github.com/opencop-oss/opencop/blob/main/backend/core/src/main/java/com/opencop/core/api/general/technical/gateway/db/userdirectory/UserDirectoryQueryService.java"
click node_websocket "https://github.com/opencop-oss/opencop/blob/main/backend/websocket/src/main/java/com/opencop/websocket/business/usecase/event/RetrieveAllEventsHandler.java"
click node_weather "https://github.com/opencop-oss/opencop/tree/main/frontend/packages/app/src/features/map"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_connect,node_connection_manager,node_socket_connectors,node_byod,node_mapper toneBlue
class node_feature_store,node_event_api,node_historical_tracks,node_watchbox toneAmber
class node_authorization,node_layer_directory,node_user_directory toneMint
class node_websocket toneRose
class node_webapp,node_map,node_render,node_session,node_plugins,node_weather,node_operator,node_source toneIndigo
```

## Components

### Data integration

- [Socket lifecycle](https://github.com/opencop-oss/opencop/blob/main/backend/connect/src/main/java/com/opencop/api/connect/business/connector/ConnectionLifecycleService.java): `backend/connect/src/main/java/com/opencop/api/connect/business/connector/ConnectionLifecycleService.java`
- [Connection manager](https://github.com/opencop-oss/opencop/blob/main/backend/connect/src/main/java/com/opencop/api/connect/business/connector/ConnectionManager.java): `backend/connect/src/main/java/com/opencop/api/connect/business/connector/ConnectionManager.java`
- [TCP UDP RTSP](https://github.com/opencop-oss/opencop/tree/main/backend/connect/src/main/java/com/opencop/api/connect/technical/gateway/socket): `backend/connect/src/main/java/com/opencop/api/connect/technical/gateway/socket`
- [Kafka BYOD](https://github.com/opencop-oss/opencop/tree/main/backend/processor/src/main/java/com/opencop/processor/technical/spring/config/byod): `backend/processor/src/main/java/com/opencop/processor/technical/spring/config/byod`
- [Field mapping](https://github.com/opencop-oss/opencop/blob/main/backend/sdk/src/main/java/com/opencop/core/sdk/ports/gateway/mapper/MapperProfileService.java): `backend/sdk/src/main/java/com/opencop/core/sdk/ports/gateway/mapper/MapperProfileService.java`

### Processing and history

- [Geographic features](https://github.com/opencop-oss/opencop/blob/main/backend/processor/src/main/java/com/opencop/processor/technical/gateway/db/PostGisService.java): `backend/processor/src/main/java/com/opencop/processor/technical/gateway/db/PostGisService.java`
- [Event history API](https://github.com/opencop-oss/opencop/tree/main/backend/core/src/main/java/com/opencop/core/api/event): `backend/core/src/main/java/com/opencop/core/api/event`
- [Historical tracks](https://github.com/opencop-oss/opencop/tree/main/backend/processor/src/main/java/com/opencop/processor/business/usecase/history): `backend/processor/src/main/java/com/opencop/processor/business/usecase/history`
- [Watchbox transitions](https://github.com/opencop-oss/opencop/blob/main/backend/processor/src/main/java/com/opencop/processor/business/usecase/watchbox/WatchboxTransitionEngine.java): `backend/processor/src/main/java/com/opencop/processor/business/usecase/watchbox/WatchboxTransitionEngine.java`

### Core services

- [Layer access](https://github.com/opencop-oss/opencop/blob/main/backend/core/src/main/java/com/opencop/core/api/general/technical/service/SourceRelationshipAuthorizationService.java): `backend/core/src/main/java/com/opencop/core/api/general/technical/service/SourceRelationshipAuthorizationService.java`
- [Layer directory](https://github.com/opencop-oss/opencop/blob/main/backend/core/src/main/java/com/opencop/core/api/iam/technical/gateway/db/layers/directory/LayerDirectoryQueryService.java): `backend/core/src/main/java/com/opencop/core/api/iam/technical/gateway/db/layers/directory/LayerDirectoryQueryService.java`
- [User directory](https://github.com/opencop-oss/opencop/blob/main/backend/core/src/main/java/com/opencop/core/api/general/technical/gateway/db/userdirectory/UserDirectoryQueryService.java): `backend/core/src/main/java/com/opencop/core/api/general/technical/gateway/db/userdirectory/UserDirectoryQueryService.java`

### Realtime delivery

- [WebSocket events](https://github.com/opencop-oss/opencop/blob/main/backend/websocket/src/main/java/com/opencop/websocket/business/usecase/event/RetrieveAllEventsHandler.java): `backend/websocket/src/main/java/com/opencop/websocket/business/usecase/event/RetrieveAllEventsHandler.java`

### Web map

- [Web application](https://github.com/opencop-oss/opencop/tree/main/frontend/packages/app/src): `frontend/packages/app/src`
- [Operational map](https://github.com/opencop-oss/opencop/tree/main/frontend/packages/app/src/features/map): `frontend/packages/app/src/features/map`
- [Render pipeline](https://github.com/opencop-oss/opencop/blob/main/frontend/packages/app/src/features/map/scene-binding/RenderPipeline.ts): `frontend/packages/app/src/features/map/scene-binding/RenderPipeline.ts`
- [Session rendering](https://github.com/opencop-oss/opencop/blob/main/frontend/packages/app/src/features/map/scene-binding/session/SessionPipeline.ts): `frontend/packages/app/src/features/map/scene-binding/session/SessionPipeline.ts`
- [Plugin tools](https://github.com/opencop-oss/opencop/blob/main/frontend/packages/contributions/src/host/PluginManager.ts): `frontend/packages/contributions/src/host/PluginManager.ts`
- [Weather overlays](https://github.com/opencop-oss/opencop/tree/main/frontend/packages/app/src/features/map): `frontend/packages/app/src/features/map`

### Other components

- **Operator**
- **External sources**

## Connections

- Operator → Web application: uses (evidence: `README.md`)
- External sources → Socket lifecycle: provides feed (evidence: `README.md`)
- External sources → Kafka BYOD: publishes records (evidence: `README.md`)
- Socket lifecycle → Connection manager: manages lifecycle (evidence: `backend/connect/src/main/java/com/opencop/api/connect/business/connector/ConnectionLifecycleService.java`)
- Connection manager → TCP UDP RTSP: starts connectors
- Kafka BYOD → Field mapping: maps fields (evidence: `README.md`)
- TCP UDP RTSP → Field mapping: maps fields (evidence: `README.md`)
- Field mapping → Geographic features: creates features (evidence: `README.md`)
- Geographic features → Operational map: feeds picture (evidence: `README.md`)
- Operator → Web application: configures sources (evidence: `README.md`)
- Web application → Operational map: explores (evidence: `README.md`)
- Operational map → Render pipeline: renders scene (evidence: `frontend/packages/app/src/features/map/scene-binding/session/SessionPipeline.ts`)
- Render pipeline → Session rendering: uses pipeline (evidence: `frontend/packages/app/src/features/map/scene-binding/session/SessionPipeline.ts`)
- Plugin tools → Operational map: extends tools (evidence: `README.md`)
- Operational map → Weather overlays: shows overlays (evidence: `README.md`)
- Operational map → Event history API: inspects history (evidence: `README.md`)
- Operational map → Historical tracks: replays movement (evidence: `README.md`)
- Event history API → WebSocket events: delivers events
- WebSocket events → Operational map: streams updates
- Geographic features → Watchbox transitions: evaluates observations
- Operator → Layer access: requests access (evidence: `README.md`)
- Layer access → Layer directory: checks layers
- Layer access → User directory: checks users