How sagarkacpl/nomination-success-story works
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: NominationController.php Nomination controller · AuthController.php Auth controller · bootstrap.php Bootstrap · index.php User pages
Components 26
Web surface
Apache entry points, rewrites, and request handlers
- .htaccess · Root rewrite boundary into public/
.htaccess - public rules · Hides .php extensions and routes clean URLs
public/.htaccess - Bootstrap · Shared web setup and security headers
public/bootstrap.php - User pages · Login, register, dashboard, verify, password, logout, and nomination pages
public/index.php - AJAX actions · Incremental save, achievement edits, delete, and final submit handlers
public/ajax/save-field.php - Admin area · Admin login, dashboard, user review, nomination review, and logout
public/admin/index.php
Application core
Controllers, models, config, and shared helpers
- Controller base · Shared controller plumbing for app logic
app/Core/Controller.php - Model base · Shared model/database plumbing
app/Core/Model.php - Session · Session lifecycle and access control support
app/Core/Session.php - Config · Environment settings, URLs, SMTP, and app options
app/Config/config.php - Database · Database connection setup and credentials
app/Config/Database.php - Auth controller · Registration, login, verification, and password reset flows
app/Controllers/AuthController.php - Nomination controller · Draft capture, submission, uploads, and PDF-facing nomination flow
app/Controllers/NominationController.php - User · Users, credentials, verification, and access checks
app/Models/User.php - Nomination · Nomination records and persisted form state
app/Models/Nomination.php - Achievement · Repeated nomination achievements and attachments
app/Models/NominationAchievement.php - Admin · Administrator authentication and management data
app/Models/Admin.php - File uploader · Upload validation and document storage handling
app/Helpers/FileUploader.php - SMTP mailer · Outbound verification and password email integration
app/Helpers/SmtpMailer.php - Validator · Shared form and security validation helpers
app/Helpers/Validator.php - Flash messages · Session-backed transient messaging for shared alerts
app/Traits/FlashMessageTrait.php
Views
Server-rendered partials and page templates
- Auth views · Login and register page templates
views/auth/login.php - Shared partials · Headers, footers, dashboards, and flash rendering
views/partials/header.php - Admin partials · Admin-specific layout and navigation templates
views/admin-partials/admin-header.php - PDF template · Server-side nomination document rendering template
resources/pdf/nomination-template.php
Storage
Uploaded documents and generated artifacts
- Uploads · Profile pictures and nomination documents
uploads/profile_pics
Connections 30
- .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