ScholarGate Identity — System Architecture & Overview

1. Executive Summary

ScholarGate Identity is an enterprise centralized Single Sign-On (SSO) and Identity & Access Management (IAM) platform engineered for secondary and higher education institutions. Operating as an identity bridge between local DAPODIK administration databases, Zitadel IAM (OpenID Connect / OAuth 2.0 PKCE), and Google Workspace, ScholarGate Identity unifies student, teacher, and staff authentication across all institutional digital services.

---

2. High-Level Architecture Diagram

flowchart TD
    subgraph ClientLayer ["1. Client & Application Ecosystem"]
        Browser["User Browser / Client App"]
        CBTApp["CBT Exam System"]
        ERaporApp["E-Rapor Application"]
        ELibraryApp["E-Library Service"]
    end

    subgraph EdgeLayer ["2. Reverse Proxy & Security Edge"]
        Nginx["Nginx Web Server (HTTPS / SSL)"]
        SecurityGate["Content Security Policy & CSRF Shield"]
    end

    subgraph CoreLayer ["3. Core ScholarGate Identity Engine (PHP 8.3+)"]
        Router["HTTP Request Router Engine"]
        ZitadelSDK["Zitadel OIDC & OAuth 2.0 PKCE Client"]
        GoogleOAuth["Google Workspace Auth Provider"]
        DapodikSync["DAPODIK Web Service Sync Engine"]
        AcademicEngine["Active Academic Year Engine"]
        EloquentORM["Illuminate Database Capsule (Eloquent)"]
    end

    subgraph DataLayer ["4. Persistence & External Authorities"]
        MariaDB[(MariaDB 10.6+ / MySQL 8.0 Database)]
        DapodikLocal[(Local DAPODIK Database Service)]
        ZitadelIAM["Zitadel IAM Cloud / On-Premise"]
    end

    Browser -->|OIDC Login Flow| Nginx
    CBTApp -->|API Key / Member Lookup| Nginx
    ERaporApp -->|Active Academic Year API| Nginx
    ELibraryApp -->|OAuth 2.0 PKCE| Nginx

    Nginx --> SecurityGate
    SecurityGate --> Router
    Router --> ZitadelSDK
    Router --> GoogleOAuth
    Router --> DapodikSync
    Router --> AcademicEngine

    ZitadelSDK -->|OIDC Protocol| ZitadelIAM
    DapodikSync -->|REST Sync| DapodikLocal
    AcademicEngine --> EloquentORM
    EloquentORM --> MariaDB

---

3. Technology Stack & Runtime Matrix

Subsystem	Technology	Version	Technical Responsibility
Backend Language	PHP	8.3+	Core identity router, authentication logic, and background processing
Database ORM	Illuminate Capsule	^10.0	Standalone Eloquent ORM for database migrations and query execution
Database Engine	MariaDB / MySQL	10.6+ / 8.0+	Relational storage for users, classes, academic years, and audit logs
Identity Provider	Zitadel IAM	OIDC 1.0	Centralized IAM supporting OpenID Connect and OAuth 2.0 PKCE flows
Google Federation	Google Workspace	OAuth 2.0	Authentication for institutional accounts
Frontend Styling	Tailwind CSS	3.4+	Custom Cloudflare Obsidian dark theme UI system
UI Component Layer	shadcn/ui primitives	Native JS	Accessible modal dialogs, Sonner toast alerts, and form controls
Testing Suite	PHPUnit	10.5+	Unit testing coverage for authentication helpers and data validators

---

4. Comprehensive Repository Anatomy

ScholarGate-Identity/
├── app/
│   ├── Controllers/               # Request Controllers
│   │   ├── AdminController.php    # Admin dashboard, academic year management & user CRUD
│   │   ├── ApiController.php      # External REST API endpoints & X-API-Key authentication
│   │   ├── AuthController.php     # OIDC / Google OAuth authentication handlers
│   │   └── DashboardController.php# Member portal views & self-service data corrections
│   ├── Helpers/                   # Core system utility functions
│   │   ├── auth_helper.php        # Session validation, password hashers & RBAC checks
│   │   ├── avatar_helper.php      # Dynamic avatar generator & Google profile parser
│   │   └── security_helper.php    # Input sanitization, CSRF tokens & domain verifiers
│   ├── Middleware/                # HTTP Interceptors
│   │   ├── AdminMiddleware.php    # Admin role guard & permissions enforcement
│   │   ├── ApiMiddleware.php      # X-API-Key validator & origin domain matcher
│   │   └── AuthMiddleware.php     # User session verification guard
│   ├── Models/                    # Standalone Eloquent ORM Models
│   │   ├── AcademicHistory.php    # Historical class & role snapshots
│   │   ├── AcademicYear.php       # School academic year & semester configuration
│   │   ├── Admin.php              # Backoffice administrator profiles & JSON permissions
│   │   ├── ApiKey.php             # External application access keys & domain whitelist
│   │   ├── ClassModel.php         # Class definitions, homeroom teachers & ordering
│   │   ├── Member.php             # Central identity model (Students, Teachers, Staff)
│   │   ├── PortalApp.php          # Integrated SSO applications catalog
│   │   └── Setting.php            # Dynamic key-value system settings
│   └── Services/                  # Integration & Background Engines
│       ├── DapodikService.php     # DAPODIK Web Service client & sync parser
│       ├── MailerService.php      # Asynchronous SMTP queue processor
│       └── ZitadelService.php     # Zitadel IAM OIDC client & PKCE generator
├── config/                        # System Configuration Files
│   ├── database.php               # Eloquent Capsule database connection manager
│   └── env.php                    # Environment file parser & Zod-like validator
├── database/
│   ├── migration.php              # Comprehensive CLI database migration & seeding wizard
│   └── schema.sql                 # Baseline SQL schema export
├── docs/                          # Project documentation files
├── public/                        # Web server document root
│   ├── index.php                  # Main application front controller
│   ├── css/                       # Compiled Tailwind & Cloudflare Obsidian stylesheets
│   └── js/                        # Alpine.js, DataTables, and shadcn component scripts
├── resources/                     # Views & template layouts
├── routes/
│   └── web.php                    # Central HTTP routing table
├── composer.json                  # PHP dependency definitions
├── nginx.conf                     # Production Nginx server block configuration
└── phpunit.xml                    # PHPUnit testing suite configuration