eCert-MBIP/docs/architecture.md

eCert MBIP — System Architecture

Overview

Sistem pengurusan sijil digital (eCert) untuk program-program yang dianjurkan oleh MBIP (Majlis Bandaraya Ipoh Perak). Sistem membolehkan admin urus program, kehadiran peserta, soalselidik, dan penjanaan sijil digital secara automatik.

---

Technology Stack

Komponen	Pilihan	Versi
Backend Framework	Laravel	12.x (latest stable)
PHP	PHP	8.5.x
Database	MySQL	8.x
Frontend CSS	Bootstrap	5.3
Frontend JS	jQuery	3.7
Template Engine	Blade	(built-in)
Asset Pipeline	Vite	(built-in Laravel)
Queue Driver	Database (→ Redis production)	—
Storage	Laravel Storage (local disk)	—

---

Composer Packages (Cadangan)

Core / Wajib

Package	Tujuan	Sebab Pilih
intervention/image:^3.0	Image manipulation untuk generate sijil	GD sudah ada, sokongan penuh Malay font TTF
barryvdh/laravel-dompdf:^3.0	Generate PDF sijil dari HTML	Standard Laravel, senang maintain
simplesoftwareio/simple-qrcode:^4.0	Generate QR Code PNG	Wrapper BaconQRCode, Laravel-friendly
league/csv:^9.0	Import CSV peserta	Ringan, tanpa dependency besar, handle UTF-8 BOM
laravel/breeze:^2.0	Admin auth scaffolding	Minimal, Blade stack, senang customise

Optional (Cadang Fasa Lanjut)

Package	Tujuan	Bila Perlukan
maatwebsite/excel:^3.1	Import Excel (.xlsx)	Jika perlu format Excel (bukan CSV)
spatie/laravel-activitylog:^4.0	Audit log	Jika audit trail perlu lebih structured

Kenapa Tidak Pakai

• Imagick: Tidak ada sebagai PHP extension dalam environment ini — guna GD sahaja.
• Laravel Sanctum/Passport: Tidak perlu — public peserta akses via token, bukan API JWT.
• Livewire/Vue/React: Tidak dalam requirement — kekal Blade + jQuery.
• Spatie Media Library: Over-engineered untuk keperluan ini — guna Laravel Storage terus.

---

Laravel Boost — Perlu Penjelasan

NOTA: "Laravel Boost" tidak jelas merujuk kepada package mana. Kemungkinan:

1. Laravel Breeze — Auth scaffolding (cadangan saya untuk admin auth)
2. Package dalaman — Jika ada package khusus MBIP/organisasi
3. Laravel Octane — Performance boost (tidak diperlukan untuk sistem ini)

Sila sahkan apa yang dimaksudkan dengan "Laravel Boost" sebelum Fasa 1 dimulakan.

---

Application Architecture

eCert MBIP
├── Admin Module (authenticated, /admin/*)
│   ├── Program Management
│   ├── QR Code Management
│   ├── Participant Management (pre-register + import)
│   ├── Certificate Template Management
│   ├── Questionnaire Management
│   └── Statistics & Reports
│
├── Public Module (token-based, /p/* dan /certificate/*)
│   ├── QR Scan → Check-in Page
│   ├── Staff Check-in Flow
│   ├── Walk-in Registration Flow
│   ├── Questionnaire Page
│   └── Certificate Download
│
└── Background Jobs (Queue)
    ├── GenerateCertificateJob
    ├── SendCertificateEmailJob
    └── BlastCertificateLinkJob

---

Key Design Decisions

1. Token-Based Public Access

• Peserta awam tidak login.
• Semua akses public guna token atau Laravel Signed URL.
• QR code bawa ke /p/{qr_token} — token UUID 64 char, bukan ID.
• Certificate download guna /certificate/{cert_token} — UUID unik per sijil.
• Questionnaire link guna participant.uuid dalam signed URL.

2. Participant Identity

• no_kp adalah pengecam unik peserta dalam sistem.
• Jika peserta hadir program berbeza, rekod participants dikongsi (cari by no_kp).
• Satu peserta boleh ada banyak program_participants dan attendances.

3. Certificate Generation Strategy

• On-demand: Sijil dijana semasa peserta minta download buat pertama kali.
• Flow: Soalselidik selesai → dispatch GenerateCertificateJob → simpan PNG → wrap PDF.
• Jika certificate.file_path sudah ada, terus serve — tidak jana semula.
• Gagal generate: simpan status = failed, log error ringkas.

4. Queue Strategy

• Development: QUEUE_CONNECTION=database (simpan dalam jobs table).
• Production: cadang QUEUE_CONNECTION=redis (perlu Redis server).
• Queue worker perlu jalan sebagai service (Supervisor di Linux / Task Scheduler di Windows).

5. File Storage

• Semua fail dalam storage/app/private/ — tidak boleh akses direct.
• Download melalui controller dengan Storage::download().
• QR code images dalam storage/app/public/qrcodes/ (boleh akses via symlink).
• Certificate template dalam storage/app/private/templates/.
• Generated certificates dalam storage/app/private/certificates/{program_uuid}/.

6. Font untuk Certificate

• Guna .ttf font file dalam storage/app/fonts/ atau resources/fonts/.
• Cadang bundel Noto Sans (Google Fonts, open source, sokong Malay charset).
• Font size perlu auto-scale berdasarkan panjang nama peserta.

7. Admin Auth

• Standard Laravel auth (email + password).
• Guna Laravel Breeze (Blade stack) untuk scaffolding.
• Semua /admin/* route dilindungi middleware auth.
• Satu role sahaja buat masa ini: admin (users table dengan is_admin flag atau role enum).

---

Security Architecture

Request Layer:
  - Rate limiting: /p/* (60/min), /certificate/* (30/min), /admin/* (unlimited)
  - CSRF protection: semua POST form
  - Input validation: FormRequest classes

Auth Layer:
  - Admin: session-based Laravel auth
  - Public: token validation + signed URL verification

Data Layer:
  - no_kp: TIDAK dalam URL — guna UUID/token sahaja
  - Sensitive files: dalam storage/app/private (tidak boleh direct access)
  - Database: prepared statements (Eloquent ORM)

Audit Layer:
  - audit_logs table: admin actions (create/update program, upload template, dll)
  - email_logs table: semua email attempt
  - certificates table: track generated_at, emailed_at, downloaded_at

---

Directory Structure (Cadangan)

app/
├── Http/
│   ├── Controllers/
│   │   ├── Admin/           ← semua admin controller
│   │   └── Public/          ← semua public controller
│   ├── Requests/            ← FormRequest validation
│   └── Middleware/
├── Models/
├── Jobs/
│   ├── GenerateCertificateJob.php
│   └── SendCertificateEmailJob.php
├── Mail/
│   └── CertificateReadyMail.php
├── Services/
│   ├── CertificateService.php   ← image manipulation logic
│   ├── QrCodeService.php
│   └── AttendanceService.php
└── Imports/
    └── ParticipantImport.php    ← CSV import logic

resources/
├── views/
│   ├── admin/               ← semua admin views
│   ├── public/              ← public check-in, questionnaire, download
│   ├── emails/              ← email templates
│   └── layouts/
│       ├── admin.blade.php
│       └── public.blade.php
├── fonts/                   ← TTF fonts untuk certificate
└── js/ + css/

storage/app/
├── public/qrcodes/          ← QR code images (accessible via symlink)
├── private/
│   ├── templates/           ← certificate template images
│   ├── certificates/        ← generated certificates
│   └── imports/             ← temporary CSV uploads