# sammagbo/controle-de-acesso architecture

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

- Interactive diagram: https://gitdiagram.com/sammagbo/controle-de-acesso
- Repository: https://github.com/sammagbo/controle-de-acesso

## Overview

MAGBO Access Control is an Electron desktop application backed by a Spring REST API for recording and governing school access. The main workflow runs from an operator selecting a point and identifying a person, through backend authorization and recording, to updated activity views. The README also documents analytics, administration, imports, CDI and meal/exit workflows, and Hikvision and Pronote integrations. Those branches are represented at their documented subsystem paths; only sampled source supports the more specific access and webhook wiring shown here.

Main entry points: [`js/api.js`](https://github.com/sammagbo/controle-de-acesso/blob/main/js/api.js) (API client), [`backend/src/main/java/com/magbo/access/repositories`](https://github.com/sammagbo/controle-de-acesso/tree/main/backend/src/main/java/com/magbo/access/repositories) (Application data), [`js/App.js`](https://github.com/sammagbo/controle-de-acesso/blob/main/js/App.js) (Operator interface), [`backend/src/main/java/com/magbo/access/controllers/AccessController.java`](https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/controllers/AccessController.java) (Access endpoints)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_desktop["Desktop operations"]
  node_electron["Electron shell<br/>[main.js]"]
  node_app["Operator interface<br/>[App.js]"]
  node_client["API client<br/>[api.js]"]
  node_adminui["Admin interface<br/>[AdminDashboard.js]"]
end

subgraph group_access["Access decisions"]
  node_accessapi["Access endpoints"]
  node_decision["Access decision"]
  node_attempts["Attempt tracking"]
  node_meals["Meal entitlements"]
  node_exits["Exit permissions"]
  node_cdi["CDI visits<br/>[CdiController.java]"]
end

subgraph group_admin["Administration and reporting"]
  node_history["Activity and reports"]
  node_analytics["Analytics and statistics"]
  node_management["User administration"]
  node_bulk["Bulk user import"]
end

subgraph group_integrations["External integrations"]
  node_webhook["Camera webhook"]
  node_pronote["Pronote synchronization"]
  node_hikvision["Hikvision cameras"]
  node_pronoteext["Pronote system"]
end

subgraph group_foundation["Security and persistence"]
  node_security["JWT and roles<br/>[JwtService.java]"]
  node_store[("Application data")]
end

node_operator(("School operator"))

node_operator -->|"uses"| node_app
node_electron -->|"loads"| node_app
node_app -->|"requests"| node_client
node_client -->|"calls API"| node_accessapi
node_accessapi -->|"delegates"| node_decision
node_decision -->|"records outcomes"| node_attempts
node_attempts -->|"persists attempts"| node_store
node_accessapi -->|"reads and writes logs"| node_store
node_client -->|"requests activity"| node_history
node_history -->|"queries attempts"| node_store
node_client -->|"requests statistics"| node_analytics
node_analytics -->|"queries access logs"| node_store
node_app -->|"renders administration"| node_adminui
node_client -->|"calls API"| node_management
node_client -->|"submits imports"| node_bulk
node_management -->|"manages users"| node_store
node_pronote -->|"synchronizes users"| node_store
node_pronote -.->|"fetches data"| node_pronoteext
node_client -->|"manages entitlements"| node_meals
node_client -->|"manages permissions"| node_exits
node_client -->|"manages visits"| node_cdi
node_meals -->|"reads and writes"| node_store
node_exits -->|"reads and writes"| node_store
node_cdi -->|"reads and writes"| node_store
node_hikvision -->|"sends events"| node_webhook
node_webhook -->|"processes recognition"| node_decision
node_client -->|"authenticates"| node_security
node_security -->|"loads user accounts"| node_store

click node_electron "https://github.com/sammagbo/controle-de-acesso/blob/main/main.js"
click node_app "https://github.com/sammagbo/controle-de-acesso/blob/main/js/App.js"
click node_client "https://github.com/sammagbo/controle-de-acesso/blob/main/js/api.js"
click node_accessapi "https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/controllers/AccessController.java"
click node_webhook "https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/controllers/HikvisionWebhookController.java"
click node_decision "https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/services/AccessDecisionService.java"
click node_attempts "https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/services/AccessAttemptService.java"
click node_history "https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/controllers/AccessAttemptController.java"
click node_analytics "https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/controllers/StatsController.java"
click node_adminui "https://github.com/sammagbo/controle-de-acesso/blob/main/js/components/AdminDashboard.js"
click node_management "https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/controllers/UserController.java"
click node_bulk "https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/controllers/UserController.java"
click node_pronote "https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/services/PronoteSyncService.java"
click node_meals "https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/services/MealEntitlementService.java"
click node_exits "https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/services/ExitPermissionService.java"
click node_cdi "https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/controllers/CdiController.java"
click node_security "https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/security/JwtService.java"
click node_store "https://github.com/sammagbo/controle-de-acesso/tree/main/backend/src/main/java/com/magbo/access/repositories"

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_electron,node_app,node_client,node_adminui toneBlue
class node_accessapi,node_decision,node_attempts,node_meals,node_exits,node_cdi toneAmber
class node_history,node_analytics,node_management,node_bulk toneMint
class node_webhook,node_pronote,node_hikvision,node_pronoteext toneRose
class node_security,node_store,node_operator toneIndigo
```

## Components

### Desktop operations

- [Electron shell](https://github.com/sammagbo/controle-de-acesso/blob/main/main.js): `main.js`
- [Operator interface](https://github.com/sammagbo/controle-de-acesso/blob/main/js/App.js): `js/App.js`
- [API client](https://github.com/sammagbo/controle-de-acesso/blob/main/js/api.js): `js/api.js`
- [Admin interface](https://github.com/sammagbo/controle-de-acesso/blob/main/js/components/AdminDashboard.js): `js/components/AdminDashboard.js`

### Access decisions

- [Access endpoints](https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/controllers/AccessController.java): `backend/src/main/java/com/magbo/access/controllers/AccessController.java`
- [Access decision](https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/services/AccessDecisionService.java): `backend/src/main/java/com/magbo/access/services/AccessDecisionService.java`
- [Attempt tracking](https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/services/AccessAttemptService.java): `backend/src/main/java/com/magbo/access/services/AccessAttemptService.java`
- [Meal entitlements](https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/services/MealEntitlementService.java): `backend/src/main/java/com/magbo/access/services/MealEntitlementService.java`
- [Exit permissions](https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/services/ExitPermissionService.java): `backend/src/main/java/com/magbo/access/services/ExitPermissionService.java`
- [CDI visits](https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/controllers/CdiController.java): `backend/src/main/java/com/magbo/access/controllers/CdiController.java`

### Administration and reporting

- [Activity and reports](https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/controllers/AccessAttemptController.java): `backend/src/main/java/com/magbo/access/controllers/AccessAttemptController.java`
- [Analytics and statistics](https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/controllers/StatsController.java): `backend/src/main/java/com/magbo/access/controllers/StatsController.java`
- [User administration](https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/controllers/UserController.java): `backend/src/main/java/com/magbo/access/controllers/UserController.java`
- [Bulk user import](https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/controllers/UserController.java): `backend/src/main/java/com/magbo/access/controllers/UserController.java`

### External integrations

- [Camera webhook](https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/controllers/HikvisionWebhookController.java): `backend/src/main/java/com/magbo/access/controllers/HikvisionWebhookController.java`
- [Pronote synchronization](https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/services/PronoteSyncService.java): `backend/src/main/java/com/magbo/access/services/PronoteSyncService.java`
- **Hikvision cameras**
- **Pronote system**

### Security and persistence

- [JWT and roles](https://github.com/sammagbo/controle-de-acesso/blob/main/backend/src/main/java/com/magbo/access/security/JwtService.java): `backend/src/main/java/com/magbo/access/security/JwtService.java`
- [Application data](https://github.com/sammagbo/controle-de-acesso/tree/main/backend/src/main/java/com/magbo/access/repositories): `backend/src/main/java/com/magbo/access/repositories`

### Other components

- **School operator**

## Connections

- School operator → Operator interface: uses
- Electron shell → Operator interface: loads
- Operator interface → API client: requests
- API client → Access endpoints: calls API
- Access endpoints → Access decision: delegates
- Access decision → Attempt tracking: records outcomes
- Attempt tracking → Application data: persists attempts
- Access endpoints → Application data: reads and writes logs
- API client → Activity and reports: requests activity
- Activity and reports → Application data: queries attempts
- API client → Analytics and statistics: requests statistics
- Analytics and statistics → Application data: queries access logs
- Operator interface → Admin interface: renders administration
- API client → User administration: calls API
- API client → Bulk user import: submits imports
- User administration → Application data: manages users
- Pronote synchronization → Application data: synchronizes users
- Pronote synchronization → Pronote system: fetches data
- API client → Meal entitlements: manages entitlements
- API client → Exit permissions: manages permissions
- API client → CDI visits: manages visits
- Meal entitlements → Application data: reads and writes
- Exit permissions → Application data: reads and writes
- CDI visits → Application data: reads and writes
- Hikvision cameras → Camera webhook: sends events
- Camera webhook → Access decision: processes recognition
- API client → JWT and roles: authenticates
- JWT and roles → Application data: loads user accounts