# natskie101/osas_beacon architecture

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

- Interactive diagram: https://gitdiagram.com/natskie101/osas_beacon
- Repository: https://github.com/natskie101/osas_beacon

## Overview

BEACON OSAS is a server-rendered student-affairs portal for students, coordinators, and administrators. Users enter through web routes, authenticate or register, then use role-scoped portal workflows for student services or administration; controllers coordinate domain operations and persist state. The README documents orientation, announcements, events, requests, support, broadcasts, notifications, analytics, and reports. The source index and excerpts support some controller-to-service/model links; unsampled feature internals are represented at their listed controller paths, with no guessed internal call chains.

Main entry points: [`routes/web.php`](https://github.com/natskie101/osas_beacon/blob/main/routes/web.php) (Web routes), [`app/Http/Controllers/Student/OrientationController.php`](https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Student/OrientationController.php) (Orientation learning), [`app/Services/FileStorage.php`](https://github.com/natskie101/osas_beacon/blob/main/app/Services/FileStorage.php) (Protected file storage), [`app/Http/Controllers/Auth/LoginController.php`](https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Auth/LoginController.php) (Authentication)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Web entry and access"]
  node_front["HTTP entry<br/>[index.php]"]
  node_bootstrap["App bootstrap<br/>[app.php]"]
  node_routes["Web routes<br/>[web.php]"]
end

subgraph group_accounts["Accounts and identity"]
  node_auth["Authentication"]
  node_registration["Student registration"]
  node_useradmin["Account management<br/>[UserController.php]"]
  node_usersvc["User operations<br/>[UserService.php]"]
end

subgraph group_student["Student services"]
  node_studentportal["Student dashboard"]
  node_announcements["Announcements"]
  node_orientation["Orientation learning"]
  node_quiz["Orientation quizzes"]
  node_studentrequests["Requests and support"]
  node_lostfound["Lost and found"]
  node_events["Events and rules"]
end

subgraph group_admin["Administration"]
  node_adminworkspace["Admin workspace"]
  node_broadcasts["Broadcast delivery"]
  node_reports["Analytics and reports"]
end

subgraph group_shared["Shared platform"]
  node_notifications["Notifications"]
  node_audit["Audit trail<br/>[AuditLogger.php]"]
  node_files["Protected file storage<br/>[FileStorage.php]"]
  node_r2["Optional R2 storage<br/>[R2Storage.php]"]
  node_database[("PostgreSQL")]
end

node_visitor(("Portal user"))

node_visitor -->|"sends requests"| node_front
node_front -->|"boots app"| node_bootstrap
node_bootstrap -->|"loads routes"| node_routes
node_routes -->|"dispatches auth"| node_auth
node_routes -->|"dispatches signup"| node_registration
node_routes -->|"dispatches admin"| node_useradmin
node_routes -->|"dispatches student"| node_studentportal
node_routes -->|"dispatches service"| node_announcements
node_routes -->|"dispatches learning"| node_orientation
node_routes -->|"dispatches support"| node_studentrequests
node_routes -->|"dispatches claims"| node_lostfound
node_routes -->|"dispatches events"| node_events
node_routes -->|"dispatches dashboard"| node_adminworkspace
node_routes -->|"dispatches broadcasts"| node_broadcasts
node_routes -->|"dispatches reports"| node_reports
node_registration -->|"creates accounts"| node_usersvc
node_useradmin -->|"manages users"| node_usersvc
node_orientation -->|"uses quiz service"| node_quiz
node_orientation -->|"stores media"| node_files
node_orientation -->|"notifies audience"| node_notifications
node_broadcasts -.->|"delivers portal alerts"| node_notifications
node_auth -->|"records sign-in"| node_audit
node_useradmin -->|"handles uploads"| node_files
node_files -->|"stores remotely"| node_r2
node_auth -.->|"reads identity"| node_database
node_usersvc -.->|"persists accounts"| node_database
node_notifications -.->|"persists alerts"| node_database
node_audit -->|"writes audit records"| node_database
node_files -->|"stores file records"| node_database

click node_front "https://github.com/natskie101/osas_beacon/blob/main/public/index.php"
click node_bootstrap "https://github.com/natskie101/osas_beacon/blob/main/bootstrap/app.php"
click node_routes "https://github.com/natskie101/osas_beacon/blob/main/routes/web.php"
click node_auth "https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Auth/LoginController.php"
click node_registration "https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Auth/RegisterController.php"
click node_useradmin "https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Admin/UserController.php"
click node_usersvc "https://github.com/natskie101/osas_beacon/blob/main/app/Services/UserService.php"
click node_studentportal "https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Student/DashboardController.php"
click node_announcements "https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Student/AnnouncementController.php"
click node_orientation "https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Student/OrientationController.php"
click node_quiz "https://github.com/natskie101/osas_beacon/blob/main/app/Services/OrientationQuizService.php"
click node_studentrequests "https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Student/SupportController.php"
click node_lostfound "https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Student/LostFoundController.php"
click node_events "https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Student/EventController.php"
click node_adminworkspace "https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Admin/DashboardController.php"
click node_broadcasts "https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Admin/BroadcastController.php"
click node_reports "https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Admin/ReportController.php"
click node_notifications "https://github.com/natskie101/osas_beacon/blob/main/app/Services/NotificationService.php"
click node_audit "https://github.com/natskie101/osas_beacon/blob/main/app/Services/AuditLogger.php"
click node_files "https://github.com/natskie101/osas_beacon/blob/main/app/Services/FileStorage.php"
click node_r2 "https://github.com/natskie101/osas_beacon/blob/main/app/Services/R2Storage.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_front,node_bootstrap,node_routes,node_visitor toneBlue
class node_auth,node_registration,node_useradmin,node_usersvc toneAmber
class node_studentportal,node_announcements,node_orientation,node_quiz,node_studentrequests,node_lostfound,node_events toneMint
class node_adminworkspace,node_broadcasts,node_reports toneRose
class node_notifications,node_audit,node_files,node_r2,node_database toneIndigo
```

## Components

### Web entry and access

- [HTTP entry](https://github.com/natskie101/osas_beacon/blob/main/public/index.php): `public/index.php`
- [App bootstrap](https://github.com/natskie101/osas_beacon/blob/main/bootstrap/app.php): `bootstrap/app.php`
- [Web routes](https://github.com/natskie101/osas_beacon/blob/main/routes/web.php): `routes/web.php`

### Accounts and identity

- [Authentication](https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Auth/LoginController.php): `app/Http/Controllers/Auth/LoginController.php`
- [Student registration](https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Auth/RegisterController.php): `app/Http/Controllers/Auth/RegisterController.php`
- [Account management](https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Admin/UserController.php): `app/Http/Controllers/Admin/UserController.php`
- [User operations](https://github.com/natskie101/osas_beacon/blob/main/app/Services/UserService.php): `app/Services/UserService.php`

### Student services

- [Student dashboard](https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Student/DashboardController.php): `app/Http/Controllers/Student/DashboardController.php`
- [Announcements](https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Student/AnnouncementController.php): `app/Http/Controllers/Student/AnnouncementController.php`
- [Orientation learning](https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Student/OrientationController.php): `app/Http/Controllers/Student/OrientationController.php`
- [Orientation quizzes](https://github.com/natskie101/osas_beacon/blob/main/app/Services/OrientationQuizService.php): `app/Services/OrientationQuizService.php`
- [Requests and support](https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Student/SupportController.php): `app/Http/Controllers/Student/SupportController.php`
- [Lost and found](https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Student/LostFoundController.php): `app/Http/Controllers/Student/LostFoundController.php`
- [Events and rules](https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Student/EventController.php): `app/Http/Controllers/Student/EventController.php`

### Administration

- [Admin workspace](https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Admin/DashboardController.php): `app/Http/Controllers/Admin/DashboardController.php`
- [Broadcast delivery](https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Admin/BroadcastController.php): `app/Http/Controllers/Admin/BroadcastController.php`
- [Analytics and reports](https://github.com/natskie101/osas_beacon/blob/main/app/Http/Controllers/Admin/ReportController.php): `app/Http/Controllers/Admin/ReportController.php`

### Shared platform

- [Notifications](https://github.com/natskie101/osas_beacon/blob/main/app/Services/NotificationService.php): `app/Services/NotificationService.php`
- [Audit trail](https://github.com/natskie101/osas_beacon/blob/main/app/Services/AuditLogger.php): `app/Services/AuditLogger.php`
- [Protected file storage](https://github.com/natskie101/osas_beacon/blob/main/app/Services/FileStorage.php): `app/Services/FileStorage.php`
- [Optional R2 storage](https://github.com/natskie101/osas_beacon/blob/main/app/Services/R2Storage.php): `app/Services/R2Storage.php`
- **PostgreSQL**

### Other components

- **Portal user**

## Connections

- Portal user → HTTP entry: sends requests
- HTTP entry → App bootstrap: boots app (evidence: `public/index.php`)
- App bootstrap → Web routes: loads routes (evidence: `bootstrap/app.php`)
- Web routes → Authentication: dispatches auth (evidence: `routes/web.php`)
- Web routes → Student registration: dispatches signup (evidence: `routes/web.php`)
- Web routes → Account management: dispatches admin (evidence: `routes/web.php`)
- Web routes → Student dashboard: dispatches student (evidence: `routes/web.php`)
- Web routes → Announcements: dispatches service (evidence: `routes/web.php`)
- Web routes → Orientation learning: dispatches learning (evidence: `routes/web.php`)
- Web routes → Requests and support: dispatches support (evidence: `routes/web.php`)
- Web routes → Lost and found: dispatches claims (evidence: `routes/web.php`)
- Web routes → Events and rules: dispatches events (evidence: `routes/web.php`)
- Web routes → Admin workspace: dispatches dashboard (evidence: `routes/web.php`)
- Web routes → Broadcast delivery: dispatches broadcasts (evidence: `routes/web.php`)
- Web routes → Analytics and reports: dispatches reports (evidence: `routes/web.php`)
- Student registration → User operations: creates accounts (evidence: `app/Http/Controllers/Auth/RegisterController.php`)
- Account management → User operations: manages users (evidence: `app/Http/Controllers/Admin/UserController.php`)
- Orientation learning → Orientation quizzes: uses quiz service (evidence: `app/Http/Controllers/Student/OrientationController.php`)
- Orientation learning → Protected file storage: stores media (evidence: `app/Http/Controllers/Student/OrientationController.php`)
- Orientation learning → Notifications: notifies audience (evidence: `app/Http/Controllers/Student/OrientationController.php`)
- Broadcast delivery → Notifications: delivers portal alerts
- Authentication → Audit trail: records sign-in (evidence: `app/Http/Controllers/Auth/LoginController.php`)
- Account management → Protected file storage: handles uploads (evidence: `app/Http/Controllers/Admin/UserController.php`)
- Protected file storage → Optional R2 storage: stores remotely (evidence: `app/Services/FileStorage.php`)
- Authentication → PostgreSQL: reads identity
- User operations → PostgreSQL: persists accounts
- Notifications → PostgreSQL: persists alerts
- Audit trail → PostgreSQL: writes audit records (evidence: `app/Services/AuditLogger.php`)
- Protected file storage → PostgreSQL: stores file records (evidence: `app/Services/FileStorage.php`)
