E Event

AGENTS.md — FLA project entry point

For any agent/assistant working on this repo: read this file, then TODO.md.

What this is

FLA Event & Awards Platform — modular, plain PHP 8.3 (no framework, no Laravel), MariaDB database, deployed on the subdomain https://event.production1.jugaar.ai (plain 443, no custom ports, no localhost URLs in shareable output). Flagship capability: public-voted, AI-assessed event awards (70% public votes / 30% board; admin veto; LinkedIn-verified voters; AI-marked category interviews in MiniMax m3; judges panel; internal ticketing; mass comms; audit log everywhere; DB-driven branding from an admin control panel).

Read order (resume in 60 seconds)

  1. TODO.md — current state, next tasks, open questions (updated every session).
  2. docs/SRS.md — full business requirements (use-cases UC-01…UC-15, FR/NFR, BR rules).
  3. docs/WORKFLOWS/ — step-by-step flows (voting, applicant, judges, winners…).
  4. ROADMAP.md — milestone plan · CHANGELOG.md · WORKFLOW.md (rules below).

All of the above are also rendered as webpages at /docs when the site runs.

Repo map

public/index.php        front controller  · public/assets (css/js) · public/.htaccess
src/bootstrap.php       autoload + env + config + session
src/routes.php          route → module controller map
src/Core/               Router DB Settings View Config Env Auth Markdown helpers
src/Core/AI/            AI gateway: ProviderInterface, MiniMaxProvider, MockProvider, Ai
src/Core/Services/      LinkedIn (client+mock), WhatsApp (null driver)
src/Core/Cards/         GdDriver (working) + AiCardDriver (reserved) + Cards factory
src/Modules/<Name>/     Home Docs Registration Branding Events Ai Voting Cards Judges
                        Tickets Comms Winners Audit Notifications Dashboard
views/                  layout + home + errors + register + docs
config/                 config.php (env-driven) · database.php
database/migrations/    001–009 SQL · database/migrate.sh (idempotent runner)
bin/card-demo.php       renders demo share cards via GD
.env / .env.example     secrets (env never committed)
docs/, *.md             the living documentation set

Rules when changing code

  • declare(strict_types=1) in every PHP file; PSR-4 under App\; modules stay

self-contained; core stays thin. PDO prepared statements; escape output with e().

  • Branding/weights/feature flags come from the DB (settings, feature_toggles) —

never hardcode brand text.

  • Keep mock mode working (NFR-08): no hard dependency on LinkedIn/AI/WhatsApp keys.
  • Follow WORKFLOW.md: SRS → workflow → code → CHANGELOG/ROADMAP/TODO →

conventional commit → annotated tag per milestone. Keep local git history always saved; never commit secrets.

  • If you change anything listed in this file (structure, commands, rules), update it.

Commands

  • Health: GET /health (JSON: app version, db, ai mode)
  • Migrate: ./database/migrate.sh (creds from .env, overridable via DB_* env)
  • Demo cards: php bin/card-demo.php
  • QA suite: ./bin/qa.sh (29 checks against the live subdomain; arg: base URL)
  • Lint: find src public config -name '*.php' -exec php -l {} +