A multi-tenant CPD platform for educational organisations, combining lesson visit assessments, coaching workflows, professional development guidance, and video-recorded classroom observations across web and mobile clients.
Executive Summary
Core Pattern
Shared Node API with React admin UI and Flutter mobile app
Education Fit
Tenant-configurable hierarchy, principles, questions, guides, and role-based workflows
Video Strategy
Direct uploads to R2 or OneDrive with mobile retry queue and provider validation
Quality Signal
Isolated server tests plus broad Flutter widget/repository coverage
Overview
The Problem
Schools need a usable system for lesson visit assessments, coaching workflows, guides, and recorded classroom observations, but those workflows span web admin, classroom/mobile capture, storage integrations, and strict role/tenant boundaries.
The Opportunity
Build a multi-tenant CPD platform with a shared backend and two fit-for-purpose clients: a React admin/data workflow UI and a Flutter mobile experience for classroom capture, analysis, and resilient video uploads.
My Role
Product architect and hands-on engineer across backend API design, data modeling, auth and storage integration, reporting pipelines, React admin workflows, and mobile architecture/testability decisions.
Constraints & Design Pressures
Architecture Decisions
The architecture separates backend domain/API concerns from two distinct clients: a web admin/data workflow interface and a mobile field app for capture, coaching, and upload resilience. The platform decisions prioritize education-domain configurability and practical video operations.
Cross-Platform Runtime Flows
Why These Decisions
Three-package monorepo (server, web, mobile)
Why: The product needed shared domain behavior across channels while allowing each client to use tooling suited to its interaction model (data-heavy web admin vs mobile classroom workflows).
Impact: Clear separation of platform responsibilities with coordinated feature delivery across backend, web, and mobile.
Dual-provider video storage (OneDrive or Cloudflare R2)
Why: Different organisations have different enterprise requirements and infrastructure preferences for video storage.
Impact: Per-org storage flexibility with a validation workflow and graceful degradation when providers are not configured.
Direct-to-storage uploads via presigned/session flows
Why: Video files should not transit the API server due to payload size, cost, and reliability concerns.
Impact: Scalable upload path, reduced server load, and better mobile upload ergonomics.
Repository pattern + dependency injection in Flutter
Why: Mobile screens needed to be testable without real HTTP calls and support feature-level isolation.
Impact: 30+ tests across screens/repos/models with mockable dependencies and better long-term maintainability.
Assessment report aggregation in MongoDB
Why: Reporting screens need filtered aggregates by principle/question with percentages and DataGrid-style filters.
Impact: Server-side aggregation keeps clients lighter and enables consistent reporting outputs across web and mobile.
Startup initialization for principles
Why: Principles are foundational to lesson assessment workflows and must exist reliably per organisation.
Impact: Reduced admin setup friction and safer assumptions across assessment forms and reports.
Friendly duplicate-key error translation in model hooks
Why: Admin-heavy workflows generate duplicate-name/email edge cases frequently and raw Mongo errors harm UX.
Impact: Cleaner user-facing validation feedback without leaking database internals.
Backend (Server)
The server is the shared backbone for both clients: authentication, hierarchy/tenant data, assessments/coaching domains, reporting aggregates, guide content, and video storage integration management.
JWT auth with bcrypt hashing, admin-created users, welcome emails, password reset tokens/expiry, first-time login flag, and bearer-token middleware verification.
Organisation, users, roles, and user-role junction models with audit/status fields and friendly duplicate-key error translation.
Lesson visit assessments capture structured question responses, strength/growth flags, notes, and org hierarchy refs, with aggregation-driven reporting by principle and question.
CoachingFeed entries and VideoVisit records connect lesson visits, coaching notes, upload status, device metadata, storage provider file references, and audit fields.
Guide collections support structured rich content blocks for application guidance, deliberate practice, instructional coaching, and project overview content.
Per-organisation StorageConfig supports R2 or OneDrive, validation status/error tracking, and secure handling of secrets in API output.
Cloudflare R2 uses S3-compatible presigned URLs; Microsoft Graph supports client-credentials auth and large-file chunked upload sessions.
Express middleware stack with Helmet/Morgan/Multer, route coverage across domain areas, and startup initialization of principles for all organisations.
Node test runner + Supertest + mongodb-memory-server enable isolated CI-friendly tests without an external database dependency.
Web Client (React)
The React client is tuned for operational/admin usage: DataGrid-based management screens, filter-heavy analytics, and content authoring tools, all layered on role-based access and persisted global state.
React 18 (CRA) + MUI v5 app with Redux Toolkit, DataGrid-heavy admin pages, role-based routing, and responsive layout patterns for data management.
Lesson visit forms and T&L reporting graphs with rich filter panels and responsive behavior for location/division/level/person/date slicing.
Coaching feed/index workflows and video visit list/playback with status filtering, aligned to backend coaching/video models.
Admin-authored guides use TipTap with a shared editor wrapper, while rendered guide content is sanitized via DOMPurify.
Separate admin pages for organisations, users, hierarchy entities, roles, principles/questions, and storage config with validation UI.
Formik/Yup validation, drag/drop file and list interactions, lightbox viewing, and utility components support higher-velocity admin workflows.
Mobile App (Flutter)
The Flutter app is not a thin wrapper. It includes role-aware analysis screens, lesson visit entry, coaching workflows, and a full in-app video recording/upload pipeline designed for inconsistent connectivity environments.
Flutter app uses repository-per-feature patterns, model serialization helpers, constructor-based dependency injection, and shared_preferences session persistence.
Drawer-based navigation groups guidance, analysis, coaching, and account experiences, including lesson visits, graphs, coaching feed/table, and guide content.
In-app camera recording with local temp storage, storage-config-aware upload selection, progress tracking, and provider-specific upload strategies.
Connectivity-aware upload retry logic queues failed video uploads and resumes processing automatically when network connectivity returns.
Permission flags lock filter fields and actions for non-admin users, aligning mobile behavior with tenant/role constraints from the backend.
30+ tests cover widgets, repositories, models, navigation, and auth flows with mocked HTTP responses and coverage reporting.
Tradeoffs & Constraints
The product balances educational workflow complexity, multi-tenant flexibility, and media-heavy mobile usage. The strongest signal is not perfection; it is clear engineering tradeoffs with obvious future hardening paths.
Two client apps (web + mobile) vs simpler single-client delivery
Rationale: School workflows span admin/data management and in-classroom capture, which have very different UX and platform requirements.
Tradeoff: Higher coordination overhead, but much better fit for each operational context.
Dual video storage provider support vs simpler single-provider integration
Rationale: Organisations may require enterprise OneDrive/SharePoint or prefer R2-style object storage.
Tradeoff: More configuration and validation complexity, but stronger tenant flexibility and adoption fit.
Direct uploads + mobile queueing vs API-proxied uploads
Rationale: Video uploads are large and mobile connectivity can be unreliable.
Tradeoff: More storage integration logic on client/server, but reduced backend load and significantly better upload resilience.
Rich admin configurability vs simpler fixed workflows
Rationale: Educational organisations differ in hierarchy structure, principles, questions, and storage constraints.
Tradeoff: Broader configuration/test surface area, but a more deployable multi-tenant product.
JWT login tokens without expiry (current login flow) vs stricter expiry model
Rationale: Pragmatic delivery choice for session simplicity in the current implementation.
Tradeoff: Operational simplicity now, but a clear security hardening opportunity for future iteration.
Outcomes / Metrics
Public metrics are not included here, but the architecture and implementation outcomes show substantial platform depth across tenant administration, instructional workflows, reporting, and video operations.
Outcomes / Delivery Signals
Quality / Maturity Signals
What I'd Improve Next
The platform already demonstrates strong cross-channel design. The next gains are in security hardening, contract standardization, and observability for media-heavy mobile workflows.
Standardize token expiry/refresh behavior (current login token lifetime is a clear hardening target).
Consider stronger initial password onboarding strategy (e.g., invite tokens/magic links) to replace deterministic password generation.
Extract shared API schemas/contracts to reduce drift between web and mobile clients over time.
Add deeper observability on mobile upload failures/retries and provider-specific error rates.
Continue modularizing larger controllers/services as feature scope expands.
Evaluate shared domain packages for validation/DTOs across server and client apps where practical.
Contact
I can help shape the backend, admin workflows, and mobile delivery architecture so the product remains usable and maintainable as it grows.