Software Requirements Specification (SRS)

FLA Event & Awards Platform — plain PHP, modular, subdomain-hosted.
Living document: every feature planned or built gets its use case recorded here
(rule in WORKFLOW.md). View this file in the browser at /docs/srs.

1. Introduction

1.1 Purpose

Define everything the platform must do, in business use-case language, so that:

• the owner knows exactly what is being built and in which order;
• any (new) development session can resume work from this file + TODO.md;
• each feature has one authoritative flow description (linked workflow docs).

1.2 Scope

A modular web platform for events whose flagship capability is public-voted, AI-assessed awards. Branding (name, logo, colors, campaign texts) is managed from an admin Control Panel — nothing brand-related is hardcoded. The platform is a single-tenant deployment on its own subdomain.

Out of scope (v1.x): payments/ticketing for paid events (not requested), native apps, multi-tenant SaaS operation.

1.3 Definitions

1.4 References

• ROADMAP.md — milestone plan · TODO.md — live session handoff
• docs/WORKFLOWS/*.md — step-by-step flows (voter flow, judge flow, …)
• WORKFLOW.md — engineering + git + documentation rules

2. Overall Description

2.1 System context

                ┌─────────────────────────────────────────────────────────┐
 Public ───────►│  https://event.production1.jugaar.ai  (Nginx :443 → PHP) │
 (browser,      │                                                         │
  mobile)       │   ┌─────────┐ ┌───────────┐ ┌────────┐ ┌─────────────┐  │
                │   │ Branding│ │ Registration│ │Voting │ │ Judges/     │  │
 LinkedIn OAuth │   │ Control │ │ (3 types)  │ │ (70%) │ │ Winners     │  │
 ◄─────────────►│   │ Panel   │ └─────┬─────┘ └───┬───┘ └─────────────┘  │
                │   └─────────┘       │           │                      │
 MiniMax m3 AI  │   ┌─────────────────┴───┐   ┌───┴────────┐             │
 ◄─────────────►│   │ AI gateway (mock/   │   │ Audit log  │             │
                │   │ live)               │   │ (append-only)            │
 WhatsApp API   │   └──────────┬──────────┘   └────────────┘             │
 ◄─────────────►│              │                                        │
 (later)        │        MariaDB (fla_event)                            │
                └─────────────────────────────────────────────────────────┘

2.2 Key decisions (locked)

2.3 Assumptions & constraints

• One person = one registration per event (BR-001); identity anchor is the LinkedIn profile.
• Voters must authenticate with LinkedIn (other providers may be added later).
• WhatsApp number is mandatory for award/GoH registrations (BR-007).
• The platform must keep working without external keys (NFR-08 mock mode).
• Every sensitive action is audit-logged (NFR-03).

3. Actors

4. Business rules

5. Functional requirements

FR-0100 — Platform, Branding & Docs

FR-0200 — Events & Categories

FR-0300 — Registration (v0.4.0)

FR-0400 — AI Engine (v0.5.0)

FR-0500 — Public Voting (v0.6.0)

FR-0600 — Share Cards (v0.6.0)

FR-0700 — Judges Panel (v0.7.0)

FR-0800 — Dashboards (v0.8.0, starter in v0.2.0)

FR-0400 — AI Engine (v0.5.0)

FR-0900 — Ticketing & Mass Comms (v0.8.0)

FR-1000 — Winners (v0.9.0)

FR-1100 — Audit (v0.9.0)

FR-1300 — Integrity & anti-fraud (v1.1.0)

FR-1200 — Notifications (v0.8.0)

6. Use-case library

Full step-by-step flows live in docs/WORKFLOWS/. Here: the contract version
(preconditions → main flow → alternates → postconditions).

UC-01 Configure branding & toggles — Admin

• Pre: admin logged in.
• Main: open Control Panel → edit name/logo/colors/campaign texts → save → changes live immediately; toggle module features on/off.
• Alt: restore defaults; invalid color rejected.
• Post: settings persisted; audit entry written.

UC-02 Manage event & categories — Admin

• Pre: admin. Main: create event (type award) → add categories → set active/order → announce (status).
• Alt: hide category (existing applicants unaffected); edit anytime.
• Post: public listing reflects active set.

UC-03 Register as visitor — Guest → Visitor · flow

• Pre: event open for registration.
• Main: open /register/visitor → LinkedIn sign-in (preferred) or basic form (+WhatsApp optional for visitors) → confirm → success page with "I am visiting" card → download/post to social.
• Alt: existing account → resume; event closed → waitlist message.
• Post: registration row type=visitor; notification.

UC-04 Apply for an award — Applicant + AI · flow

• Pre: active categories; applicant passes BR-001/BR-002 checks.
• Main: pick category → LinkedIn OAuth → profile imported → basic info + WhatsApp → photo (optional, may complete later on dashboard; required before approval) → AI interview (random category questions, AI-marked) → success page: personal share link + "I have applied" card.
• Alt: skip AI when event type = normal (BR: normal registration OK); photo may be uploaded later via POST /dashboard/photo; re-try photo upload.
• Post: registration type=award, status=submitted + ai_session; card PNG.

UC-05 Apply as Guest of Honor — GoH / Staff · flow

• Main: /guest-of-honor form (title e.g. CIO, company, bio, photo (optional, may complete later on dashboard), LinkedIn) → pending approval → admin approves (photo required) → listed.
• Alt (manual): staff uses "enter on behalf" (govt/C-level invitees) — flagged entered_by_user_id.
• Post: registration type=goh, status=pending→approved; BR-002 enforced.

UC-06 Staff manual entry — Staff

• Main: staff dashboard → "Add on behalf" → choose type → fill form (+upload photo) → confirm → record marked as manual entry.
• Post: audit entry with staff actor.

UC-07 Cast a vote — Voter · flow

• Pre: share link v/{token}; candidate approved; voting window open.
• Main: open link → LinkedIn auth → (optional) reason → Vote → confirmation + prompt to share.
• Alt: already voted (per rules) → "already voted" with change-vote policy (default: no duplicates); voting restriction relaxed mode → allowed per admin setting.
• Post: vote row; candidate count +1; notification to applicant; audit.

UC-08 AI marking & stats — System/AI

• Main: for each answer → score + feedback → session total & summary → attach to applicant → judges/admin see stats. Mock mode deterministic until key (NFR-08).

UC-09 Applicant self-view — Applicant

• Main: dashboard → own vote count, voter identities, AI stats, share link, cards, tickets, notifications.
• Alt: attempt to view others' totals → denied (BR-006).

UC-10 Judge review — Judge · flow

• Main: login → assigned scope → open contestant (profile, photo, AI stats, votes-if-enabled) → decision (approve/disapprove/needs-info) + notes → save.
• Post: per-category report aggregated for admin.

UC-11 Finalize & announce winners — Admin · flow

• Pre: voting closed; judges reported.
• Main: review blended ranking (70/30) + judges → optional veto (reason) → select winners per category → approve & lock → system announces (public page + notifications) → winner badges + cards generated → winners share.
• Post: status=winner rows; audit-locked snapshot; public results.

UC-12 Generate share card — System

• Main: on applied/visiting/winner trigger → GD render (photo + campaign text) → stored → shown for download/share. Alt: AI driver later.

UC-13 Support ticket — Applicant ↔ Staff · flow

• Main: applicant opens ticket (subject, question, media allowed) → staff replies from queue → status flow (open→pending→answered→closed).

UC-14 Mass communication — Staff

• Main: select audience → compose (email; WhatsApp when keyed) → preview recipient count → send → per-recipient status tracked.

UC-15 Review audit log — Admin

• Main: open Audit → filter by actor/action/date → drill into entries (meta JSON).

UC-17 Flag & review a suspected duplicate — System + Admin · flow

• Pre: registration submitted (any path incl. manual entry/claim).
• Main: system scans identity signals across all events → on any match: alert row created, all admins notified, audit entry → admin opens /admin/duplicates → compares side-by-side → Confirm (auto-veto new registration) or Dismiss.
• Alt: no match → nothing happens; applicant experience unchanged (flag-and-review, never auto-block).
• Post: queue item resolved; audit trail kept.

UC-16 Admin overview & AI insights — Admin

• Pre: admin logged in (event data exists for meaningful numbers; empty states otherwise).
• Main: admin home shows KPI cards with trends (7d/30d) → graphs (votes over time, funnel, per-category shares, top candidates, AI score distribution) → tabs: Audit (live filterable feed) → AI Insights (weekly summary, applicant briefs, vote-anomaly flags) → drill into any figure to its underlying list.
• Alt: AI key missing → insights panel shows mock/sample output with "waiting for AI key" notice (NFR-08).
• Post: no writes; every query scoped to admin role and covered by the JSON feeds used for charts.

FR-1600 — Integrations & venue (v1.5.0)

FR-1500 — Public API (v1.4.0)

7. Non-functional requirements

8. Integrations

9. Data model (overview)

settings · feature_toggles · users (admin/staff/judge/applicant/visitor/goh/voter) · events · categories · registrations (+public_token, entered_by_user_id) · question_bank · ai_sessions · ai_answers · votes · judge_assignments · judge_reviews · tickets · ticket_messages · audit_log · notifications · communications · communication_recipients

Key uniques: users.linkedin_id, users.email, registrations(event_id,user_id) (BR-001/002), votes(registration_id,voter_user_id) (BR-003), judge_reviews(registration_id,judge_user_id). DDL: database/migrations/001–009.

10. Open questions

1. Confirm MiniMax m3 model id + exact base URL; obtain API key (platform.minimax.io).
2. LinkedIn App credentials (OIDC scopes openid profile email).
3. WhatsApp provider: Meta Cloud API vs Twilio.
4. AI image API for share cards (later).
5. Email sender (SMTP host / transactional service) for comms & notifications.
6. Allowed vote-change policy (default: votes are final).
7. Public leaderboard visibility pre-finalization (default: admin-only, BR-006).

Answers get recorded here + in TODO.md when provided.

11. Version history