# marcuslimadev/controleportariaescolar architecture

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

- Interactive diagram: https://gitdiagram.com/marcuslimadev/controleportariaescolar
- Repository: https://github.com/marcuslimadev/controleportariaescolar

## Overview

Porta Aberta Escolar connects school staff, families, and gate operators around student safety and school communication. The central workflow is scanning a guardian badge, looking up authorized children, recording entry or exit, and making movements visible to families. Separate capabilities cover family invitations and onboarding, pickup authorizations, attendance and absences, badges, school administration, reports, and posts/events. The graph reflects documented routes and factory wiring; unsampled service internals are represented by their service paths, with uncertain calls omitted.

Main entry points: [`public/portaria/index.php`](https://github.com/marcuslimadev/controleportariaescolar/blob/main/public/portaria/index.php) (Gate scanner), [`public/portaria/convites.php`](https://github.com/marcuslimadev/controleportariaescolar/blob/main/public/portaria/convites.php) (Family invitations), [`app/Infrastructure/Persistence`](https://github.com/marcuslimadev/controleportariaescolar/tree/main/app/Infrastructure/Persistence) (PDO repositories), [`app/Services/AccessService.php`](https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/AccessService.php) (Access logging)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web entry points"]
  node_login["Login<br/>[login.php]"]
  node_portaria["Gate scanner<br/>[index.php]"]
  node_register["Access recording<br/>[registrar.php]"]
  node_familyportal["Family portal<br/>[index.php]"]
  node_admin["School admin<br/>[index.php]"]
  node_invites["Family invitations<br/>[convites.php]"]
  node_authorizationui["Pickup authorizations<br/>[autorizacoes.php]"]
end

subgraph group_safety["Access and safety"]
  node_accesslookup["Guardian lookup"]
  node_accesssvc["Access logging<br/>[AccessService.php]"]
  node_accesslog[("Movement records")]
  node_badge["Badges<br/>[BadgeService.php]"]
  node_emergency["Emergency badges"]
end

subgraph group_family["Family services"]
  node_onboarding["Family onboarding"]
  node_invitesvc["Invitation service<br/>[InviteService.php]"]
  node_guardianportal["Family dashboard"]
  node_withdrawal["Authorization service"]
end

subgraph group_school["School operations"]
  node_absence["Absence notices<br/>[AbsenceService.php]"]
  node_frequency["Attendance"]
  node_schooladmin["School records"]
  node_reports["Reports<br/>[ReportService.php]"]
  node_posts["Posts and events<br/>[PostService.php]"]
  node_interactions["Post interactions"]
  node_notifications["Notifications"]
end

subgraph group_core["Application and persistence"]
  node_authsvc["Authentication<br/>[AuthService.php]"]
  node_repos[("PDO repositories")]
  node_audit[("Audit logging")]
  node_factory["Service wiring<br/>[ServiceFactory.php]"]
end

node_staff(("School staff"))
node_families(("Families"))
node_gate(("Gate operators"))
node_mysql[("MySQL database")]
node_browserqueue[("Offline browser queue")]

node_families -->|"sign in"| node_login
node_staff -->|"sign in"| node_login
node_login -->|"authenticates"| node_authsvc
node_gate -->|"scans badge"| node_portaria
node_portaria -->|"looks up"| node_accesslookup
node_portaria -->|"submits movements"| node_register
node_portaria -->|"queues offline"| node_browserqueue
node_browserqueue -->|"syncs movements"| node_register
node_register -->|"records"| node_accesssvc
node_accesssvc -->|"writes movement"| node_accesslog
node_families -->|"views activity"| node_familyportal
node_familyportal -->|"loads dashboard"| node_guardianportal
node_guardianportal -->|"reads records"| node_repos
node_staff -->|"manages school"| node_admin
node_admin -->|"handles actions"| node_schooladmin
node_families -->|"completes invitation"| node_invites
node_gate -->|"creates invitation"| node_invites
node_invites -->|"creates invite"| node_invitesvc
node_invites -->|"submits enrollment"| node_onboarding
node_families -->|"requests pickup"| node_authorizationui
node_authorizationui -->|"manages authorization"| node_withdrawal
node_withdrawal -->|"reads and writes"| node_repos
node_staff -->|"handles absence notices"| node_absence
node_staff -->|"records attendance"| node_frequency
node_staff -->|"views reports"| node_reports
node_staff -->|"publishes updates"| node_posts
node_families -->|"reads updates"| node_posts
node_families -->|"responds to posts"| node_interactions
node_posts -->|"sends notifications"| node_notifications
node_factory -->|"constructs services"| node_repos
node_accesssvc -->|"records audit"| node_audit
node_withdrawal -->|"records audit"| node_audit
node_schooladmin -->|"records audit"| node_audit
node_repos -->|"queries and updates"| node_mysql

click node_login "https://github.com/marcuslimadev/controleportariaescolar/blob/main/public/login.php"
click node_portaria "https://github.com/marcuslimadev/controleportariaescolar/blob/main/public/portaria/index.php"
click node_register "https://github.com/marcuslimadev/controleportariaescolar/blob/main/public/portaria/registrar.php"
click node_familyportal "https://github.com/marcuslimadev/controleportariaescolar/blob/main/public/responsavel/index.php"
click node_admin "https://github.com/marcuslimadev/controleportariaescolar/blob/main/public/admin/index.php"
click node_invites "https://github.com/marcuslimadev/controleportariaescolar/blob/main/public/portaria/convites.php"
click node_authorizationui "https://github.com/marcuslimadev/controleportariaescolar/blob/main/public/responsavel/autorizacoes.php"
click node_authsvc "https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/AuthService.php"
click node_accesslookup "https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/AccessLookupService.php"
click node_accesssvc "https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/AccessService.php"
click node_accesslog "https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Infrastructure/Persistence/PdoAccessLogRepository.php"
click node_badge "https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/BadgeService.php"
click node_emergency "https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/EmergencyBadgeService.php"
click node_onboarding "https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/FamilyOnboardingService.php"
click node_invitesvc "https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/InviteService.php"
click node_guardianportal "https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/GuardianPortalService.php"
click node_withdrawal "https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/WithdrawalAuthorizationService.php"
click node_absence "https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/AbsenceService.php"
click node_frequency "https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/FrequencyService.php"
click node_schooladmin "https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/SchoolAdminService.php"
click node_reports "https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/ReportService.php"
click node_posts "https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/PostService.php"
click node_interactions "https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/PostInteractionService.php"
click node_notifications "https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/NotificationService.php"
click node_repos "https://github.com/marcuslimadev/controleportariaescolar/tree/main/app/Infrastructure/Persistence"
click node_audit "https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Infrastructure/Logging/DatabaseAuditLogger.php"
click node_factory "https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Support/ServiceFactory.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_login,node_portaria,node_register,node_familyportal,node_admin,node_invites,node_authorizationui toneBlue
class node_accesslookup,node_accesssvc,node_accesslog,node_badge,node_emergency,node_mysql,node_browserqueue toneAmber
class node_onboarding,node_invitesvc,node_guardianportal,node_withdrawal toneMint
class node_absence,node_frequency,node_schooladmin,node_reports,node_posts,node_interactions,node_notifications toneRose
class node_authsvc,node_repos,node_audit,node_factory,node_staff,node_families,node_gate toneIndigo
```

## Components

### Web entry points

- [Login](https://github.com/marcuslimadev/controleportariaescolar/blob/main/public/login.php): `public/login.php`
- [Gate scanner](https://github.com/marcuslimadev/controleportariaescolar/blob/main/public/portaria/index.php): `public/portaria/index.php`
- [Access recording](https://github.com/marcuslimadev/controleportariaescolar/blob/main/public/portaria/registrar.php): `public/portaria/registrar.php`
- [Family portal](https://github.com/marcuslimadev/controleportariaescolar/blob/main/public/responsavel/index.php): `public/responsavel/index.php`
- [School admin](https://github.com/marcuslimadev/controleportariaescolar/blob/main/public/admin/index.php): `public/admin/index.php`
- [Family invitations](https://github.com/marcuslimadev/controleportariaescolar/blob/main/public/portaria/convites.php): `public/portaria/convites.php`
- [Pickup authorizations](https://github.com/marcuslimadev/controleportariaescolar/blob/main/public/responsavel/autorizacoes.php): `public/responsavel/autorizacoes.php`

### Access and safety

- [Guardian lookup](https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/AccessLookupService.php): `app/Services/AccessLookupService.php`
- [Access logging](https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/AccessService.php): `app/Services/AccessService.php`
- [Movement records](https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Infrastructure/Persistence/PdoAccessLogRepository.php): `app/Infrastructure/Persistence/PdoAccessLogRepository.php`
- [Badges](https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/BadgeService.php): `app/Services/BadgeService.php`
- [Emergency badges](https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/EmergencyBadgeService.php): `app/Services/EmergencyBadgeService.php`

### Family services

- [Family onboarding](https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/FamilyOnboardingService.php): `app/Services/FamilyOnboardingService.php`
- [Invitation service](https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/InviteService.php): `app/Services/InviteService.php`
- [Family dashboard](https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/GuardianPortalService.php): `app/Services/GuardianPortalService.php`
- [Authorization service](https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/WithdrawalAuthorizationService.php): `app/Services/WithdrawalAuthorizationService.php`

### School operations

- [Absence notices](https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/AbsenceService.php): `app/Services/AbsenceService.php`
- [Attendance](https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/FrequencyService.php): `app/Services/FrequencyService.php`
- [School records](https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/SchoolAdminService.php): `app/Services/SchoolAdminService.php`
- [Reports](https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/ReportService.php): `app/Services/ReportService.php`
- [Posts and events](https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/PostService.php): `app/Services/PostService.php`
- [Post interactions](https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/PostInteractionService.php): `app/Services/PostInteractionService.php`
- [Notifications](https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/NotificationService.php): `app/Services/NotificationService.php`

### Application and persistence

- [Authentication](https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Services/AuthService.php): `app/Services/AuthService.php`
- [PDO repositories](https://github.com/marcuslimadev/controleportariaescolar/tree/main/app/Infrastructure/Persistence): `app/Infrastructure/Persistence`
- [Audit logging](https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Infrastructure/Logging/DatabaseAuditLogger.php): `app/Infrastructure/Logging/DatabaseAuditLogger.php`
- [Service wiring](https://github.com/marcuslimadev/controleportariaescolar/blob/main/app/Support/ServiceFactory.php): `app/Support/ServiceFactory.php`

### Other components

- **School staff**
- **Families**
- **Gate operators**
- **MySQL database**
- **Offline browser queue**

## Connections

- Families → Login: sign in
- School staff → Login: sign in
- Login → Authentication: authenticates
- Gate operators → Gate scanner: scans badge
- Gate scanner → Guardian lookup: looks up
- Gate scanner → Access recording: submits movements
- Gate scanner → Offline browser queue: queues offline
- Offline browser queue → Access recording: syncs movements
- Access recording → Access logging: records
- Access logging → Movement records: writes movement
- Families → Family portal: views activity
- Family portal → Family dashboard: loads dashboard
- Family dashboard → PDO repositories: reads records
- School staff → School admin: manages school
- School admin → School records: handles actions
- Families → Family invitations: completes invitation
- Gate operators → Family invitations: creates invitation
- Family invitations → Invitation service: creates invite
- Family invitations → Family onboarding: submits enrollment
- Families → Pickup authorizations: requests pickup
- Pickup authorizations → Authorization service: manages authorization
- Authorization service → PDO repositories: reads and writes
- School staff → Absence notices: handles absence notices
- School staff → Attendance: records attendance
- School staff → Reports: views reports
- School staff → Posts and events: publishes updates
- Families → Posts and events: reads updates
- Families → Post interactions: responds to posts
- Posts and events → Notifications: sends notifications
- Service wiring → PDO repositories: constructs services
- Access logging → Audit logging: records audit
- Authorization service → Audit logging: records audit
- School records → Audit logging: records audit
- PDO repositories → MySQL database: queries and updates