# joshua662/gate-automation-project architecture

> Architecture diagram of the GitHub repository joshua662/gate-automation-project, 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/joshua662/gate-automation-project
- Repository: https://github.com/joshua662/gate-automation-project

## Overview

Oakwood Subdivision is a role-based gate-access and resident-management system. The main physical workflow captures a vehicle plate at a gate, sends the plate for backend verification, records the access decision, updates gate status, and notifies affected users. Residents and administrators also use web portals for visitor requests, profile and account management, logs, notifications, and reports; administrators manage guards and system settings. The graph combines explicit behavior in sampled Python and Laravel excerpts with the capabilities evident from the source tree; details of unsampled controller and page wiring are intentionally left out.

Main entry points: [`server/routes/api.php`](https://github.com/joshua662/gate-automation-project/blob/main/server/routes/api.php) (Laravel API), [`server/app/Services/GateService.php`](https://github.com/joshua662/gate-automation-project/blob/main/server/app/Services/GateService.php) (Gate Decisions), [`admin-panel/src/App.tsx`](https://github.com/joshua662/gate-automation-project/blob/main/admin-panel/src/App.tsx) (Admin Web App), [`python/lpr_gate_controller.py`](https://github.com/joshua662/gate-automation-project/blob/main/python/lpr_gate_controller.py) (LPR Controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_gate["Gate Operations"]
  node_lpr["LPR Controller"]
end

subgraph group_backend["Backend Services"]
  node_laravel["Laravel API<br/>[api.php]"]
  node_gatecontroller["Gate Controller<br/>[GateController.php]"]
  node_gateservice["Gate Decisions<br/>[GateService.php]"]
  node_authcontroller["Authentication<br/>[AuthController.php]"]
  node_visitorcontroller["Visitor Requests"]
end

subgraph group_resident["Resident Portal"]
  node_client["Resident Web App<br/>[App.tsx]"]
  node_clientroutes["Resident Routes<br/>[AppRoutes.tsx]"]
  node_authservice["Resident Auth<br/>[AuthService.ts]"]
  node_residentpages["Resident Features"]
  node_visitorpages["Visitor Management"]
end

subgraph group_admin["Admin Portal"]
  node_adminapp["Admin Web App<br/>[App.tsx]"]
  node_adminauth["Admin Authentication<br/>[useAuth.ts]"]
  node_adminpages["Admin Features<br/>[AdminPage.tsx]"]
  node_guardpages["Guard Management<br/>[GuardsPage.tsx]"]
  node_reportpages["Reports<br/>[ReportsPage.tsx]"]
  node_adminapi["Admin API Client<br/>[adminApi.ts]"]
end

subgraph group_state["Application State"]
  node_gate_logs[("Gate Logs<br/>[GateLog.php]")]
  node_system_status[("System Status<br/>[SystemStatus.php]")]
  node_notifications[("Notifications<br/>[Notification.php]")]
  node_users[("User Accounts<br/>[User.php]")]
  node_updaterequests[("Update Requests<br/>[UpdateRequest.php]")]
  node_activity[("Activity Logs<br/>[ActivityLog.php]")]
end

node_camera(("Gate Cameras"))
node_arduino["Gate Hardware"]
node_resident_actor(("Resident"))
node_admin_actor(("Administrator"))

node_camera -->|"streams frames"| node_lpr
node_lpr -->|"verifies plates"| node_laravel
node_lpr -->|"commands gate"| node_arduino
node_lpr -->|"syncs status"| node_laravel
node_laravel -->|"dispatches request"| node_gatecontroller
node_gatecontroller -->|"checks access"| node_gateservice
node_gateservice -->|"records passage"| node_gate_logs
node_gateservice -->|"updates status"| node_system_status
node_gateservice -->|"creates alerts"| node_notifications
node_gateservice -->|"matches plates"| node_users
node_laravel -->|"dispatches request"| node_authcontroller
node_authcontroller -->|"authenticates accounts"| node_users
node_authcontroller -->|"records events"| node_activity
node_authcontroller -.->|"emails credentials"| node_resident_actor
node_laravel -->|"dispatches request"| node_visitorcontroller
node_visitorcontroller -->|"looks up residents"| node_users
node_visitorcontroller -->|"creates alerts"| node_notifications
node_visitorcontroller -->|"syncs decisions"| node_updaterequests
node_client -->|"renders routes"| node_clientroutes
node_clientroutes -->|"uses authentication"| node_authservice
node_authservice -->|"sends auth requests"| node_laravel
node_resident_actor -->|"uses portal"| node_client
node_clientroutes -->|"routes residents"| node_residentpages
node_clientroutes -->|"routes visitors"| node_visitorpages
node_admin_actor -->|"uses portal"| node_adminapp
node_adminapp -->|"provides auth"| node_adminauth
node_adminauth -->|"calls auth API"| node_adminapi
node_adminapi -->|"sends API requests"| node_laravel
node_adminapp -->|"routes administration"| node_adminpages
node_adminapp -->|"routes guards"| node_guardpages
node_adminapp -->|"routes reports"| node_reportpages

click node_lpr "https://github.com/joshua662/gate-automation-project/blob/main/python/lpr_gate_controller.py"
click node_laravel "https://github.com/joshua662/gate-automation-project/blob/main/server/routes/api.php"
click node_gatecontroller "https://github.com/joshua662/gate-automation-project/blob/main/server/app/Http/Controllers/Api/GateController.php"
click node_gateservice "https://github.com/joshua662/gate-automation-project/blob/main/server/app/Services/GateService.php"
click node_gate_logs "https://github.com/joshua662/gate-automation-project/blob/main/server/app/Models/GateLog.php"
click node_system_status "https://github.com/joshua662/gate-automation-project/blob/main/server/app/Models/SystemStatus.php"
click node_notifications "https://github.com/joshua662/gate-automation-project/blob/main/server/app/Models/Notification.php"
click node_authcontroller "https://github.com/joshua662/gate-automation-project/blob/main/server/app/Http/Controllers/Api/AuthController.php"
click node_users "https://github.com/joshua662/gate-automation-project/blob/main/server/app/Models/User.php"
click node_visitorcontroller "https://github.com/joshua662/gate-automation-project/blob/main/server/app/Http/Controllers/Api/VisitorController.php"
click node_updaterequests "https://github.com/joshua662/gate-automation-project/blob/main/server/app/Models/UpdateRequest.php"
click node_client "https://github.com/joshua662/gate-automation-project/blob/main/client/src/App.tsx"
click node_clientroutes "https://github.com/joshua662/gate-automation-project/blob/main/client/src/routes/AppRoutes.tsx"
click node_authservice "https://github.com/joshua662/gate-automation-project/blob/main/client/src/services/AuthService.ts"
click node_residentpages "https://github.com/joshua662/gate-automation-project/blob/main/client/src/pages/Resident/ResidentHomePage.tsx"
click node_visitorpages "https://github.com/joshua662/gate-automation-project/blob/main/client/src/pages/Visitors/VisitorManagementPage.tsx"
click node_adminapp "https://github.com/joshua662/gate-automation-project/blob/main/admin-panel/src/App.tsx"
click node_adminauth "https://github.com/joshua662/gate-automation-project/blob/main/admin-panel/src/hooks/useAuth.ts"
click node_adminpages "https://github.com/joshua662/gate-automation-project/blob/main/admin-panel/src/pages/AdminPage.tsx"
click node_guardpages "https://github.com/joshua662/gate-automation-project/blob/main/admin-panel/src/pages/GuardsPage.tsx"
click node_reportpages "https://github.com/joshua662/gate-automation-project/blob/main/admin-panel/src/pages/ReportsPage.tsx"
click node_adminapi "https://github.com/joshua662/gate-automation-project/blob/main/admin-panel/src/services/adminApi.ts"
click node_activity "https://github.com/joshua662/gate-automation-project/blob/main/server/app/Models/ActivityLog.php"

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_lpr toneBlue
class node_laravel,node_gatecontroller,node_gateservice,node_authcontroller,node_visitorcontroller toneAmber
class node_client,node_clientroutes,node_authservice,node_residentpages,node_visitorpages toneMint
class node_adminapp,node_adminauth,node_adminpages,node_guardpages,node_reportpages,node_adminapi toneRose
class node_gate_logs,node_system_status,node_notifications,node_users,node_updaterequests,node_activity,node_camera,node_arduino,node_resident_actor,node_admin_actor toneIndigo
```

## Components

### Gate Operations

- [LPR Controller](https://github.com/joshua662/gate-automation-project/blob/main/python/lpr_gate_controller.py): `python/lpr_gate_controller.py`

### Backend Services

- [Laravel API](https://github.com/joshua662/gate-automation-project/blob/main/server/routes/api.php): `server/routes/api.php`
- [Gate Controller](https://github.com/joshua662/gate-automation-project/blob/main/server/app/Http/Controllers/Api/GateController.php): `server/app/Http/Controllers/Api/GateController.php`
- [Gate Decisions](https://github.com/joshua662/gate-automation-project/blob/main/server/app/Services/GateService.php): `server/app/Services/GateService.php`
- [Authentication](https://github.com/joshua662/gate-automation-project/blob/main/server/app/Http/Controllers/Api/AuthController.php): `server/app/Http/Controllers/Api/AuthController.php`
- [Visitor Requests](https://github.com/joshua662/gate-automation-project/blob/main/server/app/Http/Controllers/Api/VisitorController.php): `server/app/Http/Controllers/Api/VisitorController.php`

### Resident Portal

- [Resident Web App](https://github.com/joshua662/gate-automation-project/blob/main/client/src/App.tsx): `client/src/App.tsx`
- [Resident Routes](https://github.com/joshua662/gate-automation-project/blob/main/client/src/routes/AppRoutes.tsx): `client/src/routes/AppRoutes.tsx`
- [Resident Auth](https://github.com/joshua662/gate-automation-project/blob/main/client/src/services/AuthService.ts): `client/src/services/AuthService.ts`
- [Resident Features](https://github.com/joshua662/gate-automation-project/blob/main/client/src/pages/Resident/ResidentHomePage.tsx): `client/src/pages/Resident/ResidentHomePage.tsx`
- [Visitor Management](https://github.com/joshua662/gate-automation-project/blob/main/client/src/pages/Visitors/VisitorManagementPage.tsx): `client/src/pages/Visitors/VisitorManagementPage.tsx`

### Admin Portal

- [Admin Web App](https://github.com/joshua662/gate-automation-project/blob/main/admin-panel/src/App.tsx): `admin-panel/src/App.tsx`
- [Admin Authentication](https://github.com/joshua662/gate-automation-project/blob/main/admin-panel/src/hooks/useAuth.ts): `admin-panel/src/hooks/useAuth.ts`
- [Admin Features](https://github.com/joshua662/gate-automation-project/blob/main/admin-panel/src/pages/AdminPage.tsx): `admin-panel/src/pages/AdminPage.tsx`
- [Guard Management](https://github.com/joshua662/gate-automation-project/blob/main/admin-panel/src/pages/GuardsPage.tsx): `admin-panel/src/pages/GuardsPage.tsx`
- [Reports](https://github.com/joshua662/gate-automation-project/blob/main/admin-panel/src/pages/ReportsPage.tsx): `admin-panel/src/pages/ReportsPage.tsx`
- [Admin API Client](https://github.com/joshua662/gate-automation-project/blob/main/admin-panel/src/services/adminApi.ts): `admin-panel/src/services/adminApi.ts`

### Application State

- [Gate Logs](https://github.com/joshua662/gate-automation-project/blob/main/server/app/Models/GateLog.php): `server/app/Models/GateLog.php`
- [System Status](https://github.com/joshua662/gate-automation-project/blob/main/server/app/Models/SystemStatus.php): `server/app/Models/SystemStatus.php`
- [Notifications](https://github.com/joshua662/gate-automation-project/blob/main/server/app/Models/Notification.php): `server/app/Models/Notification.php`
- [User Accounts](https://github.com/joshua662/gate-automation-project/blob/main/server/app/Models/User.php): `server/app/Models/User.php`
- [Update Requests](https://github.com/joshua662/gate-automation-project/blob/main/server/app/Models/UpdateRequest.php): `server/app/Models/UpdateRequest.php`
- [Activity Logs](https://github.com/joshua662/gate-automation-project/blob/main/server/app/Models/ActivityLog.php): `server/app/Models/ActivityLog.php`

### Other components

- **Gate Cameras**
- **Gate Hardware**
- **Resident**
- **Administrator**

## Connections

- Gate Cameras → LPR Controller: streams frames
- LPR Controller → Laravel API: verifies plates
- LPR Controller → Gate Hardware: commands gate
- LPR Controller → Laravel API: syncs status
- Laravel API → Gate Controller: dispatches request
- Gate Controller → Gate Decisions: checks access
- Gate Decisions → Gate Logs: records passage
- Gate Decisions → System Status: updates status
- Gate Decisions → Notifications: creates alerts
- Gate Decisions → User Accounts: matches plates
- Laravel API → Authentication: dispatches request
- Authentication → User Accounts: authenticates accounts
- Authentication → Activity Logs: records events
- Authentication → Resident: emails credentials
- Laravel API → Visitor Requests: dispatches request
- Visitor Requests → User Accounts: looks up residents
- Visitor Requests → Notifications: creates alerts
- Visitor Requests → Update Requests: syncs decisions
- Resident Web App → Resident Routes: renders routes
- Resident Routes → Resident Auth: uses authentication
- Resident Auth → Laravel API: sends auth requests
- Resident → Resident Web App: uses portal
- Resident Routes → Resident Features: routes residents
- Resident Routes → Visitor Management: routes visitors
- Administrator → Admin Web App: uses portal
- Admin Web App → Admin Authentication: provides auth
- Admin Authentication → Admin API Client: calls auth API
- Admin API Client → Laravel API: sends API requests
- Admin Web App → Admin Features: routes administration
- Admin Web App → Guard Management: routes guards
- Admin Web App → Reports: routes reports