# Phases

Historical arc: MVP skeleton/installer → webhook/domain → student quiz/admin builder → ops/analytics/update packs → v1.6 stability/transfer → v1.7 secondary+ops reliability → v1.7.1 measured callback performance and transition-range patch. This is a maintenance history, not a plan to rewrite the modular monolith.

Full roadmap for TFB Engine. Each phase builds strictly on the
previous one; do not skip ahead or implement future-phase business
logic early (see `docs/CODING_GUIDE.md` for feature-addition rules).

> **Re-scoping note (Phase 5):** the original Phase 5/6 split ("pure
> engines" then "student funnel" as two separate phases) was merged
> into a single Phase 5 ("Core Runtime Engines + Student Funnel") by
> an updated PRD, which also introduced the Product Rule Delta (see
> `docs/PRODUCT_RULES.md`). Phase 6 is now "Admin Builder" (the
> original Phase 7's scope), consuming what Phase 5 already built.
> The table below reflects the current, authoritative plan.

> **Re-scoping note (Phase 6):** the remaining original phases 07-12
> (Admin Panel Management, File/Media polish, Analytics & Reporting,
> Web Admin Panel, Hardening & Ops, Polish & Launch) were merged by
> the PRD into a single **Phase 07 — Analytics/Campaigns/Users +
> Backup/Logs + Final QA/Harden/Release**, since Phase 6 already
> delivered the Telegram admin builder (test/profile/question/option/
> result/settings/file management) that the old Phase 07/08 scoped
> separately. The table below reflects this.

| # | Name | Depends on | Status |
|---|---|---|---|
| 01 | Project Skeleton & Bootstrap | — | **Done** |
| 02 | Installer + Full Database Schema | 01 | **Done** |
| 03 | Telegram Pipeline & Security Middleware | 02 | **Done** |
| 04 | Domain Layer (Models, Repositories, Core Services) | 03 | **Done** |
| 05 | Core Runtime Engines + Student Funnel (+ Product Rule Deltas) | 04 | **Done** |
| 06 | Telegram Admin Builder + Files + Scoring UI | 05 | **Done** |
| 07 | Ops, Analytics, Hardening, Release Package | 06 | **Done — MVP complete** |

## Phase 01 — Project Skeleton & Bootstrap
**Goal:** Autoload, config, container, DB wrapper, logger, health check.
**Definition of done:** `public/index.php` GET returns health JSON without touching the DB; `tests/smoke.php` passes.

## Phase 02 — Installer + Full Database Schema
**Goal:** Persian install wizard, full schema (21 tables), seeder, `config/app.php` writer, webhook registration, install lock.
**Definition of done:** Fresh install creates all tables + seeds settings + writes config + registers webhook + locks itself against re-run.

## Phase 03 — Telegram Pipeline & Security Middleware
**Goal:** Real `TelegramClient`, `Update` DTO, secured webhook middleware pipeline, minimal system commands.
**Definition of done:** Invalid webhook secret is rejected before any business logic; `/start /help /myid /admin /cancel` work; rate limiting and maintenance mode function; no student/admin funnel exists yet.

## Phase 04 — Domain Layer (Models, Repositories, Core Services)
**Goal:** Full data-access layer so future controllers/engines never touch raw SQL/arrays.
**Definition of done:** One Model + Repository per core table; central Services (Settings/State/User/Campaign/Test/TestGraph/Session/Analytics/File/Audit/Membership) exist and are covered by `tests/phase04_domain_smoke.php`; Phase 3 webhook pipeline still passes end-to-end.
**Explicitly NOT done here:** scoring algorithm, branching runtime, full student/admin funnels.

## Phase 05 — Core Runtime Engines + Student Funnel
**Goal:** Implement the pure engines (`ProfileScoreEngine`, `WinnerSelector`, `BranchResolver`, `CallbackCodec`, `StartPayloadParser`) AND wire them into a full, working student funnel (`/start` → question loop → result delivery → channel-join check), while applying the Product Rule Delta (see `docs/PRODUCT_RULES.md`): no intro shown to students, auto-generated slugs/profile codes, question=text+options only, `single`/`dual_on_close` result display modes, optional-content-package result delivery with no placeholders, button-only CTA, and the new `/start` deep-link policy.
**Depends on:** Phase 4 repositories/services.
**Definition of done:** All Phase 5 acceptance criteria in the Phase 5 task brief pass — see `docs/PROJECT_STATUS.md` for the live checklist and `tests/phase05_score_engine_test.php` + `tests/phase05_runtime_smoke.php` for automated proof. A full student run was also verified manually end-to-end over real HTTP with a mock Telegram server (see `docs/CHANGELOG.md`).
**Explicitly NOT done here:** any admin UI to build/edit tests (Phase 6), backup/restore, analytics dashboards, real web admin panel.

## Phase 06 — Telegram Admin Builder + Files + Scoring UI — **this phase, done**
**Goal:** In-Telegram wizard to create/edit a test using Phase 4/5 services: create test (slug auto-generated, no manual entry), add profiles (Persian title only, code auto-generated), add questions (text + options only, no media), a +/- scoring UI per option/profile (floor 0, Product Rules §6), result content editor (optional text/voice/CTA per Product Rules §8-9), a way to set `result_display_mode`/`threshold` with the Persian guidance text already anticipated in `docs/PRODUCT_RULES.md` §7, an activation gate that blocks publishing a structurally-incomplete test, a Telegram-native file library, and an editable-settings screen for the Phase 5 settings keys admins actually need to touch. Must not show `tests.description`/intro fields to students (still enforced at the runtime layer regardless of what the admin UI allows editing).
**Depends on:** 05.
**Definition of done:** All PRD §14/§15 acceptance scenarios pass — see `docs/PROJECT_STATUS.md` for the live checklist and `tests/phase06_admin_unit.php` + `tests/phase06_validation_test.php` + `tests/phase06_soft_join_test.php` + `tests/phase06_admin_e2e.php` + `tests/phase06_admin_more_test.php` for automated proof (136 assertions total), plus a full zero-regression re-run of every Phase 1-5 test suite. See `docs/CHANGELOG.md` for the two real bugs found and fixed during verification.
**Explicitly NOT done here:** full analytics dashboards, backup/restore, a real web admin panel (only `docs/WEB_ADMIN_READINESS.md` was updated), broadcast messaging, user ban/unban UI (the data layer for these already exists from Phase 4, just no Telegram UI yet).

## Phase 07 — Ops, Analytics, Hardening, Release Package — **this phase, done, MVP complete**
**Goal:** Admin-facing conversion-rate/funnel-drop-off analytics dashboards (reading from `analytics_events`, whose write API has existed since Phase 4/5), campaign management UI with attribution reporting, user management (search/ban/unban/direct-message) from inside Telegram, pure-PDO backup/restore tooling (no shell dependency), a centralized diagnostic logging system (`Tfb\Logging\Diagnostic`/`ProblemsLog`) covering the entire codebase, a Telegram-native logs/health viewer, installer polish, and a final comprehensive security/performance hardening + QA pass before release.
**Depends on:** 06.
**Definition of done:** All acceptance scenarios in the Phase 07 task brief pass — see `docs/PROJECT_STATUS.md` for the live checklist and `tests/phase07_ops_e2e.php` (31 assertions) for automated proof, plus a full zero-regression re-run of every Phase 1-6 test suite (12 files total) and a full manual installer walkthrough over real HTTP. See `docs/CHANGELOG.md` for the three real bugs found and fixed during verification (an XSS-escaping bug, a backup-file-deletion bug, and a SQL-statement-splitting bug).
**Explicitly NOT done here (out of scope, not started):** a graphical/full web admin panel (only `docs/WEB_ADMIN_READINESS.md` was updated, per the project's PRD constraint), additional funnel types beyond `flow_type = 'quiz'`, CTA click-tracking (`AnalyticsEvents::CTA_CLICKED` remains unwritten).

## MVP status

This concludes the planned roadmap. There is no Phase 08 currently
defined — see `docs/PROJECT_STATUS.md` "MVP is complete" for what
remains genuinely out of scope vs. what could be built in a future,
not-yet-scoped phase.