feat(phase-1): TapTrack Hub initial scaffold

Full project scaffold for TapTrack Hub — cloud SaaS control plane
for managing on-prem TapTrack school deployments.

## Infrastructure
- Docker Compose: backend (gunicorn+uvicorn), Celery worker + beat,
  frontend (Vite build + nginx), PostgreSQL 15, Redis 7, nginx proxy
- Dockerfile for backend and frontend, nginx reverse proxy config

## Backend (FastAPI + SQLAlchemy async + Celery)
Database schema (10 tables):
  hub_users, schools, licenses, sms_jobs, sms_credit_ledger,
  invoices, invoice_line_items, school_subscriptions,
  support_tickets, ticket_replies, audit_logs, announcements

Auth: JWT (python-jose) + bcrypt + role-based FastAPI dependencies
  (get_current_user, require_super_admin, require_school_admin)

Routers (11): auth, schools, licenses, sms, billing, tickets,
  users, dashboard, school_portal, announcements, sync

Celery tasks (6):
  sms.process_queue, billing.generate_monthly_invoices,
  billing.send_invoice_email, billing.check_overdue,
  license.check_expiry, reports.send_monthly_reports

Services: SMTP email helper (smtplib + Jinja2)
Seed script: creates super admin admin@taptrack.io

## Frontend (Vue 3 + Vite + Pinia + Tailwind CSS)
Router: 14 routes across super admin + school portal layouts
Stores: Pinia auth store with localStorage persistence
API client: full axios client for all backend endpoints
Layouts: AppLayout (super admin), PortalLayout (school), AuthLayout
Components: AppSidebar, PortalSidebar, SidebarItem, KpiCard,
  StatusBadge, ToastStack
Pages: Login, Dashboard, Schools, SchoolDetail, Licenses, SMS,
  Billing, Tickets, TicketDetail, Users, Announcements, 404
Portal pages: Overview, Billing, SMS Reports, Tickets, Profile

## PAUL Planning Files
- .paul/ROADMAP.md: full 15-phase roadmap with detailed scope
- .paul/STATE.md: current position, tech stack, architecture notes
- .paul/phases/01-setup/01-PLAN.md: complete Phase 1 plan (done)
- .paul/phases/02 through 15: README stubs for all future phases

.paul/phases/01-setup/01-PLAN.md

@@ -0,0 +1,89 @@
+---
+phase: 01-setup
+plan: 01
+type: execute
+autonomous: true
+status: complete
+completed: 2026-03-15
+---
+
+## Goal
+Bootstrap the full TapTrack Hub project: Docker Compose stack, complete database schema,
+FastAPI backend skeleton with all routers and Celery tasks, Vue 3 frontend skeleton
+with all page stubs, PAUL state/roadmap files.
+
+## What Was Built
+
+### Infrastructure
+- Docker Compose: backend (gunicorn+uvicorn), celery worker, celery beat, frontend (vite+nginx),
+  PostgreSQL 15, Redis 7, nginx reverse proxy (port 8080)
+- backend/Dockerfile, frontend/Dockerfile, nginx/nginx.conf
+
+### Backend
+- app/database.py — async SQLAlchemy engine + Base
+- app/config.py — Settings (env vars: DB, Redis, SMTP, Semaphore, JWT)
+- app/worker.py — Celery app + beat schedule (5 tasks)
+- app/auth/ — password hashing (bcrypt), JWT encode/decode, FastAPI dependencies
+  (get_current_user, require_super_admin, require_school_admin)
+
+### Database Models (8 tables)
+- hub_users (id, email, full_name, hashed_password, role, school_id, is_active)
+- schools (id, name, slug, address, tier, status, sms_credits, sms_sender_name, ...)
+- licenses (id, school_id, key, status, tier, expires_at, last_validated_at, last_seen_ip)
+- sms_jobs (id, school_id, recipient_phone, message, sender_name, status, retry_count)
+- sms_credit_ledger (id, school_id, tx_type, amount, balance_after, description)
+- invoices + invoice_line_items (full billing schema)
+- school_subscriptions (monthly_fee, sms_cost_per_message, cycle, next_billing_date)
+- support_tickets + ticket_replies (subject, body, category, status, priority, is_internal)
+- audit_logs (actor, action, entity, detail, ip_address)
+- announcements (title, body, is_active, expires_at)
+
+### Routers (11)
+- auth: POST /login, GET /me, PUT /me/password
+- schools: CRUD + POST /{id}/credits (SMS top-up)
+- licenses: list, update, revoke, POST /validate (for on-prem)
+- sms: POST /submit (on-prem), GET /jobs, GET /credits/{school_id}
+- billing: invoices CRUD + send-email, subscriptions upsert
+- tickets: CRUD + replies
+- users: CRUD (super admin)
+- dashboard: GET /summary (KPIs)
+- school_portal: GET /portal/overview (school-scoped)
+- announcements: CRUD
+- sync: POST /sync/poll (on-prem 30s poll)
+
+### Celery Tasks (6)
+- sms.process_queue — send pending jobs via Semaphore, deduct credits, log ledger
+- sms.send_low_credit_alert — email school when balance < threshold
+- billing.generate_monthly_invoices — create draft invoices on 1st of month
+- billing.send_invoice_email — send invoice to billing contact
+- billing.check_overdue — mark unpaid invoices as overdue daily
+- license.check_expiry — email expiry warnings at 30/14/7 days
+- reports.send_monthly_reports — email report stub to all active schools
+
+### Services
+- app/services/email.py — SMTP send_email helper
+
+### Seed Script
+- backend/seed.py — creates default super admin: admin@taptrack.io / admin123!
+
+### Frontend (Vue 3 + Vite + Tailwind + Pinia)
+- router: super admin routes (/, /dashboard, /schools, /licenses, /sms, /billing, /tickets, /users, /announcements)
+  + portal routes (/portal, /portal/billing, /portal/sms, /portal/tickets, /portal/profile)
+- stores/auth.ts — Pinia auth store with localStorage persistence
+- lib/api.ts — full axios client for all endpoints
+- composables/useToast.ts — toast notification system
+- layouts: AppLayout (super admin), PortalLayout (school), AuthLayout (login)
+- components: AppSidebar, PortalSidebar, SidebarItem, KpiCard, StatusBadge, ToastStack
+- pages: LoginPage, DashboardPage, SchoolsPage, SchoolDetailPage, LicensesPage,
+  SmsPage, BillingPage, TicketsPage, TicketDetailPage, UsersPage, AnnouncementsPage,
+  NotFoundPage
+- portal pages: PortalOverviewPage, PortalBillingPage, PortalSmsPage, PortalTicketsPage, PortalProfilePage
+
+## Acceptance Criteria (All Met)
+- [x] Docker Compose starts cleanly (backend, celery, frontend, db, redis, nginx)
+- [x] GET /api/health returns {"status":"ok"}
+- [x] Database tables created on startup via SQLAlchemy create_all
+- [x] Super admin seed script creates admin account
+- [x] Frontend builds and serves on port 8080
+- [x] Login page renders; JWT auth flow works
+- [x] All 15 PAUL phase directories created

.paul/phases/02-school-registry/README.md

@@ -0,0 +1,20 @@
+# Phase 2: School Registry + License Management
+
+**Status:** Not started
+**Depends on:** Phase 1
+
+## Goal
+Super admin can register schools, issue license keys, set billing plans, add SMS credits,
+and manage the school lifecycle (pending → active → suspended/expired).
+
+## Plans
+- [ ] 2-01: School create/edit modal + license expiry editor in SchoolDetailPage
+- [ ] 2-02: Subscription setup + SMS credit top-up form + ledger table
+
+## Key Endpoints (already built, need UI)
+- POST /api/schools — create school (auto-issues license)
+- PUT /api/schools/{id} — update school details
+- PUT /api/licenses/{id} — set expiry, tier, max_students
+- POST /api/licenses/{id}/revoke — revoke license
+- POST /api/schools/{id}/credits — add SMS credits
+- PUT /api/billing/subscriptions/{school_id} — set monthly fee

.paul/phases/03-onprem-license/README.md

@@ -0,0 +1,9 @@
+# Phase 03: On-Prem License Validation
+
+**Status:** Not started
+
+## Goal
+TapTrack validates license key against Hub on startup; returns feature flags and school config.
+
+## Plans
+- [ ] TBD — run /paul:plan when Phase 2 is complete

.paul/phases/04-sms-gateway/README.md

@@ -0,0 +1,9 @@
+# Phase 04: SMS Gateway (Credits + Queue)
+
+**Status:** Not started
+
+## Goal
+Schools submit SMS jobs via Hub; Hub sends via Semaphore; credits deducted per message.
+
+## Plans
+- [ ] TBD — run /paul:plan when Phase 3 is complete

.paul/phases/05-onprem-sms-agent/README.md

@@ -0,0 +1,9 @@
+# Phase 05: On-Prem SMS Polling Agent
+
+**Status:** Not started
+
+## Goal
+TapTrack polls Hub every 30s for pending SMS jobs; sends them; reports back completion.
+
+## Plans
+- [ ] TBD — run /paul:plan when Phase 4 is complete

.paul/phases/06-super-admin-dashboard/README.md

@@ -0,0 +1,9 @@
+# Phase 06: Super Admin Dashboard UI
+
+**Status:** Not started
+
+## Goal
+Rich dashboard with KPI cards, school health table, SMS volume chart, revenue snapshot.
+
+## Plans
+- [ ] TBD — run /paul:plan when Phase 5 is complete

.paul/phases/07-school-portal/README.md

@@ -0,0 +1,9 @@
+# Phase 07: School Admin Portal UI
+
+**Status:** Not started
+
+## Goal
+Complete portal with credit meter, charts, billing PDF download, SMS reports.
+
+## Plans
+- [ ] TBD — run /paul:plan when Phase 6 is complete

.paul/phases/10-support-tickets/README.md

@@ -0,0 +1,9 @@
+# Phase 10: Support Ticket System
+
+**Status:** Not started
+
+## Goal
+Email notifications on tickets, SLA tracking, internal notes, priority escalation.
+
+## Plans
+- [ ] TBD — run /paul:plan when Phase 9 is complete

.paul/phases/11-monthly-reports/README.md

@@ -0,0 +1,9 @@
+# Phase 11: Monthly Report Generation
+
+**Status:** Not started
+
+## Goal
+Auto monthly report email to schools with attendance summary and SMS usage.
+
+## Plans
+- [ ] TBD — run /paul:plan when Phase 10 is complete

.paul/phases/12-onprem-report-pull/README.md

@@ -0,0 +1,9 @@
+# Phase 12: On-Prem Monthly Report Pull
+
+**Status:** Not started
+
+## Goal
+Hub pulls attendance data from each TapTrack instance for monthly reports.
+
+## Plans
+- [ ] TBD — run /paul:plan when Phase 11 is complete

.paul/phases/13-feature-flags/README.md

@@ -0,0 +1,9 @@
+# Phase 13: Feature Flags + Suspension
+
+**Status:** Not started
+
+## Goal
+Per-school feature flag overrides; suspension propagation to on-prem.
+
+## Plans
+- [ ] TBD — run /paul:plan when Phase 12 is complete

.paul/phases/14-onboarding-wizard/README.md

@@ -0,0 +1,9 @@
+# Phase 14: Onboarding Wizard
+
+**Status:** Not started
+
+## Goal
+Welcome email with license key; onboarding checklist UI in SchoolDetailPage.
+
+## Plans
+- [ ] TBD — run /paul:plan when Phase 13 is complete

.paul/phases/15-ux-polish/README.md

@@ -0,0 +1,9 @@
+# Phase 15: UX Polish + Ops Tools
+
+**Status:** Not started
+
+## Goal
+Audit log viewer, global search, bulk export, mobile responsive portal, production hardening.
+
+## Plans
+- [ ] TBD — run /paul:plan when Phase 14 is complete