# sagarkacpl/nomination-success-story architecture

> Architecture diagram of the GitHub repository sagarkacpl/nomination-success-story, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sagarkacpl/nomination-success-story
- Repository: https://github.com/sagarkacpl/nomination-success-story

## Overview

1. **Overall shape**
   - This is a plain-PHP, Apache-served application split into a small reusable application layer under `app/` and web entry points under `public/`.
   - The repo is not a framework app; it uses a custom autoloader, custom base `Controller`/`Model` classes, and direct PHP pages as route handlers.

2. **Request routing and document-root boundary**
   - The project root `.htaccess` rewrites requests into `public/` so the browser never needs to expose `public` in the URL.
   - `public/.htaccess` hides `.php` extensions, so URLs like `/register`, `/dashboard`, and `/logout` map to the corresponding PHP files.
   - This creates a strong boundary: `app/` contains business logic and is intended to be non-web-accessible, while `public/` is the actual HTTP surface area.

3. **Entry points and page composition**
   - The main user-facing entry points live in `public/`: login, register, dashboard, verify, password reset/change, logout, and nomination-related pages.
   - Shared rendering is done through `views/partials/*` and `views/auth/*`, which keep page markup separate from controller logic.
   - Flash messaging is centralized via `FlashMessageTrait` and rendered through a shared partial.

4. **Core application layer**
   - `app/Core/Controller.php`, `Model.php`, and `Session.php` provide the base plumbing for request handling, database access, and session state.
   - `app/Config/config.php` and `Database.php` define environment-level settings such as URLs, DB credentials, and SMTP settings.
   - `autoload.php` wires class loading without Composer-based framework bootstrapping.

5. **Authentication subsystem**
   - `app/Controllers/AuthController.php` and `app/Models/User.php` implement registration, login, email verification, password reset/change, and session-backed access control.
   - The auth flow is backed by the public pages `login`, `register`, `verify`, `forgot-password`, `reset-password`, `change-password`, `logout`, and `dashboard`.
   - Security features called out in the README are architectural, not incidental: password hashing, CSRF protection, session regeneration, brute-force lockout, and verification tokens.

6. **Nomination workflow subsystem**
   - The tree shows a separate nomination domain centered on `app/Controllers/NominationController.php` and models `Nomination` and `NominationAchievement`.
   - Public pages such as `registration.php`, `nomination-pdf.php`, and `dashboard.php` suggest a multi-step nomination/registration flow distinct from basic auth.
   - The process appears to support draft data capture, attachment upload, final submission, and later PDF viewing.

7. **Autosave and AJAX-backed draft editing**
   - `public/ajax/save-field.php`, `save-achievement.php`, `delete-achievement.php`, and `final-submit.php` indicate the nomination form is not a single submit-only form.
   - `public/assets/js/registration-autosave.js` and related scripts likely push incremental field changes to the server while the user edits.
   - This creates a client-side/draft persistence flow: browser JS → AJAX endpoint → controller/model → database.

8. **File and document handling**
   - `app/Helpers/FileUploader.php` manages uploads, and the `uploads/` tree stores profile images and nomination documents.
   - Uploads are stored outside `app/`/`views/` and appear to be organized by user or nomination ID, with randomized filenames.
   - The architecture separates binary document storage from application code and from the PDF template layer.

9. **Email and external service integration**
   - `app/Helpers/SmtpMailer.php` is the mail boundary, used for verification and likely password reset flows.
   - The README specifically mentions SMTP configuration and Gmail app passwords, so outbound email is a first-class integration point.
   - Mail is used as part of identity proofing rather than as a generic notification service.

10. **Admin back office**
    - `public/admin/*` is a separate operational surface for administrators, with its own login, dashboard, user management, nomination management, and logout.
    - Admin pages have dedicated partials under `views/admin-partials/`, so the admin UI is isolated from the user UI.
    - `public/admin/nomination-pdf-view.php` suggests admins can inspect and review submitted nomination documents directly.

11. **PDF generation and reporting**
    - `resources/pdf/nomination-template.php` and the `nomination-pdf` pages indicate server-side rendering of nomination data into a PDF-like output or template-driven document.
    - The PDF layer sits downstream of persisted nomination data and uploaded files, serving a review/export use case rather than primary data entry.

12. **Data layer and persistence**
    - `app/Config/Database.php` plus the model classes imply PDO-backed persistence with prepared statements.
    - The README emphasizes security and schema-driven setup, so the database is the system of record for users, sessions/tokens, login attempts, nominations, and achievements.
    - The application likely relies on separate tables for auth, draft nomination state, attachment metadata, and admin operations.

13. **Frontend asset layer**
    - `public/assets/js/` contains behavior-specific scripts for auth, password change, autosave, document uploads, and state/city data.
    - `public/assets/css/style.css` is the shared visual layer across auth, user dashboard, and admin pages.
    - The frontend is server-rendered first, with JS enhancing the nomination workflow and validation.

14. **Security and operational boundaries**
    - The repo is architected around explicit security controls: CSRF, output escaping, session hardening, secure uploads, and security headers in `public/bootstrap.php`.
    - Apache rewrite rules, writable upload directories, and SMTP/DB configuration are the main operational dependencies.
    - In an architecture diagram, the important trust boundaries are: browser vs public web surface, public pages vs `app/` internals, app vs database, and app vs SMTP/file storage.

Main entry points: [`app/Controllers/NominationController.php`](https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Controllers/NominationController.php) (Nomination controller), [`app/Controllers/AuthController.php`](https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Controllers/AuthController.php) (Auth controller), [`public/bootstrap.php`](https://github.com/sagarkacpl/nomination-success-story/blob/main/public/bootstrap.php) (Bootstrap), [`public/index.php`](https://github.com/sagarkacpl/nomination-success-story/blob/main/public/index.php) (User pages)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_web["Web surface"]
  node_root_htaccess[".htaccess<br/>rewrite rules<br/>[.htaccess]"]
  node_public_htaccess["public rules<br/>url mapping<br/>[.htaccess]"]
  node_bootstrap["Bootstrap<br/>[bootstrap.php]"]
  node_public_pages["User pages<br/>public entrypoints<br/>[index.php]"]
  node_ajax_api["AJAX actions<br/>draft API<br/>[save-field.php]"]
  node_admin_surface["Admin area<br/>admin entrypoints<br/>[index.php]"]
end

subgraph group_app["Application core"]
  node_controller_base["Controller base<br/>mvc base<br/>[Controller.php]"]
  node_model_base["Model base<br/>mvc base<br/>[Model.php]"]
  node_session["Session<br/>state service<br/>[Session.php]"]
  node_config["Config<br/>settings<br/>[config.php]"]
  node_database[("Database<br/>pdo config<br/>[Database.php]")]
  node_auth_controller["Auth controller<br/>auth workflow<br/>[AuthController.php]"]
  node_nomination_controller["Nomination controller<br/>nomination workflow"]
  node_user_model["User<br/>auth model<br/>[User.php]"]
  node_nomination_model["Nomination<br/>domain model<br/>[Nomination.php]"]
  node_achievement_model["Achievement<br/>domain model"]
  node_admin_model["Admin<br/>[Admin.php]"]
  node_uploader["File uploader<br/>file service<br/>[FileUploader.php]"]
  node_mailer["SMTP mailer<br/>email service<br/>[SmtpMailer.php]"]
  node_validator["Validator<br/>input validation<br/>[Validator.php]"]
  node_flash["Flash messages<br/>ui trait"]
end

subgraph group_ui["Views"]
  node_auth_views["Auth views<br/>templates<br/>[login.php]"]
  node_partials["Shared partials<br/>layout templates<br/>[header.php]"]
  node_admin_partials["Admin partials<br/>layout templates<br/>[admin-header.php]"]
  node_pdf_template["PDF template<br/>report template"]
end

subgraph group_storage["Storage"]
  node_uploads_store[("Uploads<br/>file storage")]
end

node_root_htaccess -->|"rewrites into"| node_public_htaccess
node_public_htaccess -->|"routes to"| node_public_pages
node_public_htaccess -->|"routes to"| node_ajax_api
node_bootstrap -->|"loads"| node_config
node_bootstrap -->|"starts"| node_session
node_public_pages -->|"uses"| node_auth_controller
node_public_pages -->|"uses"| node_nomination_controller
node_ajax_api -->|"calls"| node_nomination_controller
node_admin_surface -->|"uses"| node_admin_model
node_controller_base -->|"supports"| node_model_base
node_auth_controller -->|"extends"| node_controller_base
node_nomination_controller -->|"extends"| node_controller_base
node_auth_controller -->|"reads/writes"| node_user_model
node_auth_controller -->|"sends"| node_mailer
node_auth_controller -->|"validates"| node_validator
node_nomination_controller -->|"reads/writes"| node_nomination_model
node_nomination_controller -->|"reads/writes"| node_achievement_model
node_nomination_controller -->|"stores files"| node_uploader
node_nomination_controller -->|"renders"| node_pdf_template
node_user_model -->|"queries"| node_database
node_admin_model -->|"queries"| node_database
node_nomination_model -->|"queries"| node_database
node_achievement_model -->|"queries"| node_database
node_uploader -->|"writes to"| node_uploads_store
node_auth_views -->|"composed with"| node_partials
node_admin_surface -->|"renders with"| node_admin_partials
node_public_pages -->|"renders with"| node_partials
node_flash -->|"renders in"| node_partials
node_bootstrap -->|"boots"| node_auth_views
node_bootstrap -->|"boots"| node_admin_partials

click node_root_htaccess "https://github.com/sagarkacpl/nomination-success-story/blob/main/.htaccess"
click node_public_htaccess "https://github.com/sagarkacpl/nomination-success-story/blob/main/public/.htaccess"
click node_bootstrap "https://github.com/sagarkacpl/nomination-success-story/blob/main/public/bootstrap.php"
click node_public_pages "https://github.com/sagarkacpl/nomination-success-story/blob/main/public/index.php"
click node_ajax_api "https://github.com/sagarkacpl/nomination-success-story/blob/main/public/ajax/save-field.php"
click node_admin_surface "https://github.com/sagarkacpl/nomination-success-story/blob/main/public/admin/index.php"
click node_controller_base "https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Core/Controller.php"
click node_model_base "https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Core/Model.php"
click node_session "https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Core/Session.php"
click node_config "https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Config/config.php"
click node_database "https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Config/Database.php"
click node_auth_controller "https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Controllers/AuthController.php"
click node_nomination_controller "https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Controllers/NominationController.php"
click node_user_model "https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Models/User.php"
click node_nomination_model "https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Models/Nomination.php"
click node_achievement_model "https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Models/NominationAchievement.php"
click node_admin_model "https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Models/Admin.php"
click node_uploader "https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Helpers/FileUploader.php"
click node_mailer "https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Helpers/SmtpMailer.php"
click node_validator "https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Helpers/Validator.php"
click node_flash "https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Traits/FlashMessageTrait.php"
click node_auth_views "https://github.com/sagarkacpl/nomination-success-story/blob/main/views/auth/login.php"
click node_partials "https://github.com/sagarkacpl/nomination-success-story/blob/main/views/partials/header.php"
click node_admin_partials "https://github.com/sagarkacpl/nomination-success-story/blob/main/views/admin-partials/admin-header.php"
click node_pdf_template "https://github.com/sagarkacpl/nomination-success-story/blob/main/resources/pdf/nomination-template.php"
click node_uploads_store "https://github.com/sagarkacpl/nomination-success-story/tree/main/uploads/profile_pics"

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_root_htaccess,node_public_htaccess,node_bootstrap,node_public_pages,node_ajax_api,node_admin_surface toneBlue
class node_controller_base,node_model_base,node_session,node_config,node_database,node_auth_controller,node_nomination_controller,node_user_model,node_nomination_model,node_achievement_model,node_admin_model,node_uploader,node_mailer,node_validator,node_flash toneAmber
class node_auth_views,node_partials,node_admin_partials,node_pdf_template toneMint
class node_uploads_store toneRose
```

## Components

### Web surface

Apache entry points, rewrites, and request handlers

- [.htaccess](https://github.com/sagarkacpl/nomination-success-story/blob/main/.htaccess): rewrite rules · Root rewrite boundary into public/ · `.htaccess`
- [public rules](https://github.com/sagarkacpl/nomination-success-story/blob/main/public/.htaccess): url mapping · Hides .php extensions and routes clean URLs · `public/.htaccess`
- [Bootstrap](https://github.com/sagarkacpl/nomination-success-story/blob/main/public/bootstrap.php): web bootstrap · Shared web setup and security headers · `public/bootstrap.php`
- [User pages](https://github.com/sagarkacpl/nomination-success-story/blob/main/public/index.php): public entrypoints · Login, register, dashboard, verify, password, logout, and nomination pages · `public/index.php`
- [AJAX actions](https://github.com/sagarkacpl/nomination-success-story/blob/main/public/ajax/save-field.php): draft API · Incremental save, achievement edits, delete, and final submit handlers · `public/ajax/save-field.php`
- [Admin area](https://github.com/sagarkacpl/nomination-success-story/blob/main/public/admin/index.php): admin entrypoints · Admin login, dashboard, user review, nomination review, and logout · `public/admin/index.php`

### Application core

Controllers, models, config, and shared helpers

- [Controller base](https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Core/Controller.php): mvc base · Shared controller plumbing for app logic · `app/Core/Controller.php`
- [Model base](https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Core/Model.php): mvc base · Shared model/database plumbing · `app/Core/Model.php`
- [Session](https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Core/Session.php): state service · Session lifecycle and access control support · `app/Core/Session.php`
- [Config](https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Config/config.php): settings · Environment settings, URLs, SMTP, and app options · `app/Config/config.php`
- [Database](https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Config/Database.php): pdo config · Database connection setup and credentials · `app/Config/Database.php`
- [Auth controller](https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Controllers/AuthController.php): auth workflow · Registration, login, verification, and password reset flows · `app/Controllers/AuthController.php`
- [Nomination controller](https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Controllers/NominationController.php): nomination workflow · Draft capture, submission, uploads, and PDF-facing nomination flow · `app/Controllers/NominationController.php`
- [User](https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Models/User.php): auth model · Users, credentials, verification, and access checks · `app/Models/User.php`
- [Nomination](https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Models/Nomination.php): domain model · Nomination records and persisted form state · `app/Models/Nomination.php`
- [Achievement](https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Models/NominationAchievement.php): domain model · Repeated nomination achievements and attachments · `app/Models/NominationAchievement.php`
- [Admin](https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Models/Admin.php): admin model · Administrator authentication and management data · `app/Models/Admin.php`
- [File uploader](https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Helpers/FileUploader.php): file service · Upload validation and document storage handling · `app/Helpers/FileUploader.php`
- [SMTP mailer](https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Helpers/SmtpMailer.php): email service · Outbound verification and password email integration · `app/Helpers/SmtpMailer.php`
- [Validator](https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Helpers/Validator.php): input validation · Shared form and security validation helpers · `app/Helpers/Validator.php`
- [Flash messages](https://github.com/sagarkacpl/nomination-success-story/blob/main/app/Traits/FlashMessageTrait.php): ui trait · Session-backed transient messaging for shared alerts · `app/Traits/FlashMessageTrait.php`

### Views

Server-rendered partials and page templates

- [Auth views](https://github.com/sagarkacpl/nomination-success-story/blob/main/views/auth/login.php): templates · Login and register page templates · `views/auth/login.php`
- [Shared partials](https://github.com/sagarkacpl/nomination-success-story/blob/main/views/partials/header.php): layout templates · Headers, footers, dashboards, and flash rendering · `views/partials/header.php`
- [Admin partials](https://github.com/sagarkacpl/nomination-success-story/blob/main/views/admin-partials/admin-header.php): layout templates · Admin-specific layout and navigation templates · `views/admin-partials/admin-header.php`
- [PDF template](https://github.com/sagarkacpl/nomination-success-story/blob/main/resources/pdf/nomination-template.php): report template · Server-side nomination document rendering template · `resources/pdf/nomination-template.php`

### Storage

Uploaded documents and generated artifacts

- [Uploads](https://github.com/sagarkacpl/nomination-success-story/tree/main/uploads/profile_pics): file storage · Profile pictures and nomination documents · `uploads/profile_pics`

## Connections

- .htaccess → public rules: rewrites into · Root web requests are funneled into the public document root
- public rules → User pages: routes to · Extensionless URLs map to PHP entrypoints
- public rules → AJAX actions: routes to · AJAX endpoints are exposed through the same public web surface
- Bootstrap → Config: loads · Shared bootstrap reads application settings
- Bootstrap → Session: starts · Web bootstrap initializes session and security state
- User pages → Auth controller: uses · Authentication pages delegate to auth workflow logic
- User pages → Nomination controller: uses · Nomination-facing pages delegate to domain workflow logic
- AJAX actions → Nomination controller: calls · Autosave and submit actions update draft nomination state
- Admin area → Admin: uses · Admin pages authenticate and manage administrative state
- Controller base → Model base: supports · Controllers rely on shared model/database plumbing
- Auth controller → Controller base: extends · Auth workflow inherits base controller behavior
- Nomination controller → Controller base: extends · Nomination workflow inherits base controller behavior
- Auth controller → User: reads/writes · Registration, login, verification, and reset state are stored in user records
- Auth controller → SMTP mailer: sends · Verification and reset emails are sent through SMTP
- Auth controller → Validator: validates · Credentials and form input are checked centrally
- Nomination controller → Nomination: reads/writes · Nomination drafts and submissions persist here
- Nomination controller → Achievement: reads/writes · Repeated achievements are managed as a separate domain object
- Nomination controller → File uploader: stores files · Document uploads are validated and saved to disk
- Nomination controller → PDF template: renders · Submitted nomination data is formatted for document viewing/export
- User → Database: queries · User and auth state is stored in the database
- Admin → Database: queries · Administrator management uses the database as system of record
- Nomination → Database: queries · Nomination records are persisted in the database
- Achievement → Database: queries · Achievement rows are persisted in the database
- File uploader → Uploads: writes to · Uploaded files land in writable storage outside the app layer
- Auth views → Shared partials: composed with · Auth pages reuse shared page chrome and alerts
- Admin area → Admin partials: renders with · Admin UI uses isolated admin layout templates
- User pages → Shared partials: renders with · User-facing pages use shared headers, footers, and dashboards
- Flash messages → Shared partials: renders in · Flash messages are surfaced through a shared partial
- Bootstrap → Auth views: boots · Public pages load page templates after bootstrap
- Bootstrap → Admin partials: boots · Admin pages load admin templates after bootstrap
