01 — Product Overview (Shared Platform)

• 1. Purpose
• 2. Business goals
• 3. User goals (top level; per-role detail in each module's 02)
• 4. Stakeholders
• 5. Why this exists
• 6. Platform dependencies (backend)
• 7. Success metrics (platform)
• 8. Global edge cases
• 9. Global assumptions
• 10. Glossary

StudyLyon — Multi-Tenant ERP & School Management Platform. This is the shared foundation document referenced by every module design package.

1. Purpose

StudyLyon is a production-grade, multi-tenant SaaS platform that lets educational institutions (K-12 schools, colleges, coaching centers, training institutes) manage their full operational lifecycle: admissions, academics, attendance, assessments, finance, communication, transport, and library — from a single codebase.

This design-docs collection specifies the client application (Flutter, forward-looking) against the existing NestJS API. The backend is the source of truth for all features, routes, permissions, and data contracts.

2. Business goals

3. User goals (top level; per-role detail in each module's 02)

• Super Admin (platform): onboard institutions, monitor platform health, never touch tenant data.
• Org Admin: run the institution from one dashboard; configure everything; invite staff.
• Teacher: mark attendance, set homework, enter marks with minimal taps; mobile-friendly.
• Accountant: invoices, payments, dues, financial reports; no academic write access.
• Staff/Receptionist: manage profiles, support admin workflows, read across modules.
• Parent: track child's attendance, results, fees, and alerts proactively.
• Student: clear, simple views of homework, results, attendance, fees.
• Ops roles (Transport Manager, Librarian, HR, Principal): run their domain module.

4. Stakeholders

Platform operator (SaaS vendor), institution administrators, teaching staff, non-teaching staff, parents/guardians, students, system actors (notification engine, BullMQ workers, audit logger, webhook consumer), and the engineering/design/QA teams consuming these docs.

5. Why this exists

Institutions run fragmented tooling (paper registers, manual ledgers, physical notices, ad-hoc WhatsApp groups). StudyLyon consolidates these into one tenant-isolated platform with real-time visibility for every stakeholder. The client docs exist because the Phase 3 roadmap calls for a mobile companion; these documents are written to the full API surface so the client can grow to full parity.

6. Platform dependencies (backend)

• Node 24, NestJS 11, strict TypeScript
• MongoDB + Mongoose (shared DB, per-tenant isolation via tenantId)
• Redis: cache (sl:{tenantId}:{key}), rate limiting, BullMQ broker
• BullMQ queues: emails, push, whatsapp, in-app, attendance-process, biometric-sync, invoice-generate, payment-reminder, report-generate, audit-write, tenant-purge, cache-rebuild, webhook-deliver, admission-reminder, admission-expiry
• Storage: STORAGE_PROVIDER interface — Appwrite (Phase 1), Cloudflare R2 (Phase 2), local dev
• WebSockets: WsModule gateway for realtime delivery
• Email (SMTP), push (FCM), WhatsApp (planned)

7. Success metrics (platform)

• Tenant onboarding < 15 min
• Attendance marking latency < 1 s
• Notification delivery P95 < 30 s
• API P95 latency < 200 ms
• 99.9% uptime; zero-downtime deploys
• 100% RBAC enforcement; audit trail on every CUD action

8. Global edge cases

• Tenant isolation violations (cross-tenant ID access) → 403/404, never leak
• JWT expiry mid-session → silent refresh, re-auth on failure
• Offline operation → cached reads, queued writes with idempotency
• Concurrent updates → optimistic lock (version field), 409/422 conflict
• Soft-deleted records never appear in lists
• Rate limiting (429) on auth + API tiers
• Large lists (>100 rows) → pagination, not infinite scroll alone
• Notification fan-out failures → retry + DLQ, user sees "pending" not "failed"

9. Global assumptions

• PRD conflict (flagged): PRODUCT_REQUIREMENTS_DOCUMENT.md:144 puts native mobile apps out of Phase 1 scope; roadmap Phase 3 plans a read-only companion. Decision made with the product owner: these docs specify a full-featured Flutter client now, to the complete API surface. Any conflict with the web-first roadmap is resolved in favor of these docs unless the roadmap is amended.
• No UI design system exists in the repo → Material 3 tokens in 02_Design_Tokens.md are proposed defaults, marked as such, until a designer finalizes them.
• No device/push-token registry exists → push-related flows are forward-looking, flagged.
• Client architecture (Bloc/Cubit) is a recommendation, not an implemented decision.
• API endpoints marked "planned" come from docs/IMPLEMENTATION_PLAN.md and may not be in code yet; they are flagged (planned) in every doc.

10. Glossary