Product System Design

Last updated: 2026-05-21

Status: working architecture blueprint. This is the target design for turning the current starter monorepo into the product described in the portfolio/spec notes: a mobile-first trust engine for schools, starting with smart attendance and growing into an AI-first operating system.

Inputs Read

Product inputs:

• /home/shabir/Documents/Portfolio/School Management OS.md
• /home/shabir/Documents/Portfolio/School Management OS - Spec.md
• /home/shabir/Documents/Starter AI-First Smart System README.md

Repo inputs:

• README.md, PROJECT.md, AGENTS.md, DESIGN.md
• /docs/ai-first-workflow
• /docs/architecture
• /docs/architecture/adr-0001-strong-default-overridable
• App code in apps/web, apps/mobile, apps/nest-api, apps/docs, and apps/rust
• Installed Next.js docs under apps/web/node_modules/next/dist/docs/

External research was refreshed on 2026-05-21. References are listed at the end.

Executive Direction

Starter should be built as a secure modular monolith first, with event-driven seams and clear module boundaries, then split into independent services only when load, team ownership, or compliance pressure justifies it.

The highest-value product loop is:

Student arrives -> attendance event -> parent alert -> live dashboard -> AI risk/update signal

The safest engineering loop is:

Write source-of-truth change in Postgres
-> write outbox event in same transaction
-> worker delivers notifications, realtime updates, AI jobs, and analytics
-> every side effect is idempotent and auditable

Day one should not run Postgres, MySQL, Kafka, Redis, multiple API frameworks, and AI services as equal peers. That would add distributed-system cost before the product has stable workflows. The best initial production stack is:

• Next.js web dashboard.
• Expo mobile app for parents, teachers, guards, and bus conductors.
• Hono API as the primary product API.
• Postgres as the only source-of-truth database.
• Redis for cache, rate limits, short-lived locks, and lightweight queues.
• A worker process for outbox delivery, scheduled jobs, reminders, and AI pipelines.
• S3-compatible object storage for files, report cards, receipts, and media.
• Optional FastAPI AI service once model workflows need Python ML libraries.
• Kafka or Redpanda later, only after multiple independent consumers need durable event streams.

Product Boundaries

Starter is not a full ERP, LMS content marketplace, social network, or accounting system. It is a school trust, communication, attendance, operations, finance, and intelligence platform.

Primary personas:

High-Level Architecture

                    +----------------------+
                    |   apps/docs          |
                    |   product docs       |
                    +----------+-----------+
                               |
+----------------+     +-------v--------+      +------------------+
| apps/web       |     | apps/hono-api  |      | apps/mobile      |
| Next dashboard |<--->| Product API    |<---->| Expo app         |
+----------------+     +-------+--------+      +------------------+
                               |
               +---------------+----------------+
               |                                |
       +-------v--------+              +--------v---------+
       | Postgres       |              | Redis            |
       | source of truth|              | cache/locks/jobs |
       +-------+--------+

			  +--------+---------+
               |                                |
       +-------v-------------------------------v---------+
       | Worker runtime                                  |
       | outbox, schedules, notifications, AI jobs        |
       +---+------------+----------------+----------------+
           |            |                |
   +-------v--+  +------v------+  +------v------+  +----------------+
   | WhatsApp |  | Email/SMS   |  | Payments    |  | Object storage |
   | provider |  | providers   |  | gateway     |  | S3/R2          |
   +----------+  +-------------+  +-------------+  +----------------+

Later:
  apps/fastapi AI service, Kafka/Redpanda event bus, dedicated realtime gateway.

Service Design

Stage 1: MVP Production Services

Stage 2: Services To Split Only When Needed

Stage 3: Microservice Candidates

Only split after clear operational pressure:

• identity-service: users, sessions, memberships, roles, permissions.
• attendance-service: attendance sessions, scans, daily summaries.
• communication-service: announcements, chat, notification commands.
• finance-service: invoices, payments, ledger, receipts.
• academics-service: timetable, homework, assessments, report cards.
• transport-service: routes, trips, locations, bus attendance.
• ai-intelligence-service: student profiles, risk signals, actions, agent runs.

Until then, keep them as modules inside apps/hono-api/src/modules.

Internal Communication

Synchronous Calls

Use HTTP JSON for direct request/response flows:

• Browser/mobile -> Hono API.
• Hono API -> payment provider, WhatsApp provider, map provider, object storage.
• Hono API -> FastAPI AI service later, only through a typed internal client.

Rules:

• Every request has x-request-id.
• Authenticated requests derive tenantId, userId, and role from the session, not from the body.
• Service-to-service calls use service JWTs or mTLS once split.
• Public contracts use OpenAPI. TypeScript internal clients may use Hono RPC where useful.

Asynchronous Events

Start with a transactional outbox table in Postgres:

domain write + outbox_events insert in one transaction
worker polls pending outbox events
worker marks processing/sent/failed with retry count
consumer side effects use idempotency keys

This is enough for the MVP and protects against lost notifications without Kafka.

Add Kafka/Redpanda when all are true:

• More than two independent consumers need the same events.
• Replaying historical events becomes useful.
• Worker polling becomes a bottleneck.
• Analytics, AI, notification, and audit pipelines need independent scaling.

Kafka does not remove the need for idempotency. External APIs such as WhatsApp, SMS, email, and payment providers are still at-least-once from our perspective.

Database Strategy

Primary Decision

Use Postgres as the only source-of-truth database.

Do not add MySQL as a second operational database for the core product. It increases migration, query, backup, consistency, and team complexity without improving the MVP. Use MySQL only as an integration target/source when a school or acquirer has legacy MySQL data.

Use Redis as cache and coordination, not as a database for records that must survive or be audited.

Use pgvector in Postgres for early AI/RAG search. Move to a dedicated vector database only if Postgres vector indexes cannot meet recall, latency, memory, or filtering requirements.

Tenancy Model

Use a shared Postgres database and shared tables with tenant_id on every tenant-owned table.

Why:

• Affordable private schools are small to mid-size.
• Shared tables simplify migrations and cross-tenant product analytics.
• Tenant isolation can be enforced with app authorization and Postgres row-level security.
• Enterprise isolation can still be offered later with dedicated DB/schema deployments.

Tenant rules:

• Every business table has tenant_id.
• Every query includes tenant scope at the repository layer.
• Postgres Row Level Security should be enabled for high-risk tables before production.
• tenant_id from the client body is ignored for authenticated writes.
• Cross-tenant admin access requires explicit platform role and audit trail.

Shared Columns

Most tenant-owned tables should have:

Hard-delete only ephemeral records such as expired verification codes, sessions, temporary files, and completed idempotency keys after retention.

Core Database Tables

This is a product-level data model, not a final Prisma migration. Final schema should be added in bounded modules with tests.

Identity, Tenancy, And Authorization

Authorization model:

• RBAC for coarse permissions.
• ABAC for record-level checks: teacher sees assigned sections, parent sees linked students, conductor sees assigned route, principal sees campus/tenant.
• Policy files live beside each module: attendance.policy.ts, finance.policy.ts, etc.

People And School Structure

Attendance

Statuses:

• present, absent, late, excused, left_early, unknown.

Event types:

• arrival_scanned, departure_scanned, manual_marked, absence_detected, parent_confirmed_absence, correction_approved.

Communication And Notifications

Academics

Finance And Admin

Finance rules:

• Payments are append-only; corrections use adjustment entries.
• Verify payment webhooks with provider signatures.
• Use idempotency keys for all payment create/capture/webhook flows.
• Do not store card data.

Transport

Location retention should be short. Store detailed GPS samples for operational windows, then roll up or delete according to policy.

AI, Intelligence, And Automation

AI actions never directly change high-risk records without either deterministic policy approval or human review. High-risk records include attendance corrections, finance actions, student risk flags, discipline notes, emergency alerts, and parent-facing academic summaries.

Platform And Operations

API Route Design

Expose versioned product APIs under /api/v1. The current /auth/* Hono routes can remain during transition, but new product routes should be versioned.

Response envelope:

{
	"success": true,
	"code": 200,
	"message": "OK",
	"data": {},
	"requestId": "req_..."
}

Error envelope:

{
	"success": false,
	"code": 400,
	"message": "Validation failed",
	"errorCode": "VALIDATION_ERROR",
	"errors": [{ "field": "email", "message": "Invalid email" }],
	"requestId": "req_..."
}

Core Routes

Product Routes

Route rules:

• Use plural nouns for resources.
• Use path params only for identity, not filters.
• Use query params for filters: ?sectionId=&date=&status=.
• Use commands for non-CRUD actions: /approve, /reject, /generate, /share.
• Every mutating route accepts an optional Idempotency-Key header.
• Pagination uses cursor-based pagination: ?limit=50&cursor=....

Frontend And Mobile Route Map

Next.js Web

Use App Router route groups:

apps/web/src/app
+-- (public)
|   +-- page.tsx
|   +-- login/page.tsx
|   +-- register/page.tsx
+-- (dashboard)
|   +-- dashboard/page.tsx
|   +-- attendance/page.tsx
|   +-- students/page.tsx
|   +-- communication/page.tsx
|   +-- academics/page.tsx
|   +-- finance/page.tsx
|   +-- transport/page.tsx
|   +-- admissions/page.tsx
|   +-- ai-actions/page.tsx
|   +-- settings/page.tsx
+-- api/...

Next.js guidance from the installed docs supports route groups for organization without changing URLs, route handlers for backend-for-frontend endpoints, and a dedicated data access layer for server-side authorization and minimal DTOs. For Starter, use direct Hono API calls through a small DAL/client and do not pass full database objects into client components.

Expo Mobile

Use role-oriented route groups:

apps/mobile/src/app
+-- (auth)/login.tsx
+-- (teacher)/home.tsx
+-- (teacher)/attendance-scan.tsx
+-- (teacher)/homework.tsx
+-- (parent)/home.tsx
+-- (parent)/children/[studentId].tsx
+-- (parent)/fees.tsx
+-- (parent)/messages.tsx
+-- (guard)/scan.tsx
+-- (bus)/trip.tsx

Mobile storage rules:

• Store refresh/session handles in expo-secure-store, not plain async storage.
• Do not treat device storage as the source of truth.
• Sync write actions through server idempotency keys.
• Queue offline scans locally with signed scan payloads and expire them quickly.

Event And Kafka Design

Domain Event Names

Use past-tense names for facts:

• attendance.arrival_scanned.v1
• attendance.departure_scanned.v1
• attendance.absence_detected.v1
• notification.delivery_requested.v1
• notification.delivery_succeeded.v1
• finance.invoice_issued.v1
• finance.payment_received.v1
• academics.homework_assigned.v1
• transport.bus_location_recorded.v1
• ai.student_signal_created.v1
• ai.action_suggested.v1
• audit.security_event_recorded.v1

Event envelope:

{
	"eventId": "evt_...",
	"eventType": "attendance.arrival_scanned.v1",
	"occurredAt": "2026-05-21T09:00:00Z",
	"tenantId": "ten_...",
	"actor": { "type": "user", "id": "usr_..." },
	"aggregate": { "type": "student", "id": "stu_..." },
	"requestId": "req_...",
	"payload": {}
}

Kafka Topics Later

If Kafka/Redpanda is introduced:

Partition by tenant plus aggregate when ordering matters. Keep consumers idempotent with unique processed-event records.

Cache, Queue, And Memory Strategy

Use cache-aside for read-heavy data:

Rules:

• Do not cache payment mutation results as authority.
• Do not use write-behind for attendance, finance, or consent records.
• Use Redis locks only for short critical sections, not long business workflows.
• Use process memory only for static config, compiled templates, and permission maps with short TTLs.

Core Algorithms

QR Attendance

Use signed, rotating QR payloads:

payload = tenantId + studentId + tokenId + expiresAt + nonce
signature = HMAC(payload, tenantAttendanceSecret)

Rules:

• QR tokens expire.
• Do not expose raw student IDs without signature.
• Scans are idempotent by (session_id, student_id, direction, source_event_id).
• Late/absent classification is deterministic from bell schedule and grace period.

Attendance State Machine

unknown -> present
unknown -> absent
unknown -> late
present -> left_early
absent -> excused
any -> corrected, with approval/audit

Automated absence job:

for each active attendance session after grace window:
  find enrolled students without present/late mark
  create absence_detected event
  create absence mark
  enqueue parent notification
  update daily summary
  create student signal if pattern threshold reached

Bus ETA

Start simple:

• Haversine distance from current bus location to ordered stops.
• Rolling average speed by route segment.
• Geofence arrival/departure when bus enters/leaves stop radius.

Improve later:

• Map matching with provider APIs.
• Kalman smoothing for noisy GPS.
• Route-specific historical ETA model.

Timetable Scheduling

Phase 1:

• Manual timetable editor.
• Deterministic conflict detection: teacher overlap, room overlap, section overlap, working hours.

Phase 2:

• Constraint solver such as OR-Tools CP-SAT for auto-scheduling.
• Hard constraints: teacher availability, class hours, room capacity, subject frequency.
• Soft constraints: avoid teacher overload, distribute hard subjects, minimize gaps.

Student Intelligence Score

Start with explainable deterministic scoring, not black-box prediction.

Inputs:

• Attendance trend.
• Late frequency.
• Homework completion.
• Assessment trajectory.
• Concept mastery decline.
• Parent engagement.
• Fee stress signal, used carefully and never as an academic punishment.
• Behavior notes.

Output:

{
	"studentId": "stu_...",
	"lifeScore": 84,
	"attendanceRisk": "medium",
	"learningRisk": "low",
	"parentEngagement": 72,
	"reasonCodes": [
		"absent_2_mondays_in_4_weeks",
		"math_score_declined_12_percent"
	],
	"confidence": 0.74
}

Principles:

• Show reason codes.
• Track score version.
• Allow human feedback.
• Monitor false positives.
• Do not use risk score as punishment or exclusion.

Notification Routing

Algorithm:

choose channel from priority + consent + parent preference + message urgency
dedupe by recipient + template + aggregate + time window
send through provider
retry with exponential backoff
fail over channel when allowed
record provider status

Priority order:

• Emergency: app push + WhatsApp + SMS, with admin confirmation.
• Attendance safety: WhatsApp first, SMS fallback.
• Finance: WhatsApp/email, payment link signed and expiring.
• General announcements: app push + WhatsApp/email based on preference.

Parent Channel Preference

Phase 1:

• Rule-based preference from explicit settings and recent response history.

Phase 2:

• Thompson sampling or another conservative multi-armed bandit for send-time/channel choice.
• Optimize response probability, not pressure.
• Respect consent and quiet hours.

AI And RAG

Use AI as a supervised assistant:

• Generate report card comments for teacher approval.
• Draft parent messages.
• Summarize daily/Friday briefings.
• Explain student risk signals.
• Generate homework/test variants from approved curriculum context.
• Answer parent questions only from tenant-approved knowledge.

Implementation:

• Use structured outputs for any AI result consumed by code.
• Use tenant-filtered retrieval from Postgres/pgvector.
• Store prompt versions and model versions.
• Run evals before changing prompts/models.
• Use human approval for high-risk actions.

RAG retrieval:

query -> tenant filter -> vector search -> permission filter -> rerank -> answer with citations

Do not let AI tools call unrestricted product APIs. Each tool must have:

• A typed schema.
• Permission checks.
• Tenant scope.
• Rate limits.
• Audit logging.
• Dry-run mode for sensitive actions.

Security And Privacy Design

Starter handles minors, location, attendance, education records, parent contact data, and payment events. Treat it as high-sensitivity software from the start.

Security Baseline

The current web auth context supports Hono cookie auth but still supports Python/Rust bearer tokens stored in localStorage. Before production, standardize on cookie/BFF style auth for the web and SecureStore-backed sessions for mobile.

Privacy And Compliance

Build for these obligations even before formal legal review:

• Data minimization: collect only what is required for school operations.
• Purpose limitation: student data is used for the school service, not advertising.
• Parental/school consent tracking for minors.
• Guardian access controls: guardians only see linked students.
• Location privacy: short retention for bus GPS samples.
• Biometric caution: face recognition should be optional, consented, region-aware, and off by default. Avoid it in the MVP unless a pilot specifically requires it.
• Export/delete workflows for legal requests.
• Vendor registry for WhatsApp/SMS/email/payment/AI processors.
• Regional data residency option later for enterprise deals.

AI Safety

Rules:

• AI cannot silently mark students risky without evidence and human-visible reason codes.
• AI cannot send high-impact parent messages without review unless it is a pre-approved template filled with deterministic facts.
• AI cannot make payment, discipline, enrollment, or exclusion decisions.
• Every AI output used in the product stores prompt version, model, input references, output, and reviewer decision where applicable.
• RAG answers must be tenant-scoped and cite internal sources.
• Prompt injection tests become part of evals for parent chatbot and admin assistant.

Observability And Operations

Use OpenTelemetry for traces, metrics, and logs once services move beyond simple local development.

Minimum telemetry:

• Request count, latency, and error rate by route.
• DB query latency by module.
• Outbox queue depth and retry count.
• Notification send latency, provider status, and delivery success.
• Attendance scan latency.
• Payment webhook processing time and duplicate count.
• AI cost, latency, refusal/error rate, approval rate, and edit rate.
• Tenant-level rate limit events.

Operational targets for the attendance MVP:

Backups:

• Postgres point-in-time recovery.
• Daily logical backup drill.
• Object storage versioning for important generated documents.
• Restore test before production pilots.

Naming Conventions

Database

• Table names: snake_case, plural nouns.
• Columns: snake_case.
• Foreign keys: `<entity>_id`.
• Join tables: `<left>_<right>` or domain phrase such as student_guardians.
• Enum values: lowercase snake case in product docs; map to ORM enum style as needed.
• Indexes: `idx_<table>_<columns>`.
• Unique constraints: `uniq_<table>_<columns>`.

API

• Paths: lowercase kebab-case or simple plural nouns.
• JSON fields: camelCase.
• Route resources: plural nouns.
• Commands: verb suffix routes only when not plain CRUD, for example /approve, /generate.
• Error codes: uppercase snake case, for example AUTH_TOKEN_NOT_FOUND.

TypeScript

• Components: PascalCase file and export names.
• Hooks: useThing.
• Services: ThingService.
• Repositories: ThingRepository.
• Validators: thing.validator.ts.
• Policies: thing.policy.ts.
• Events: thing.events.ts.
• Tests: colocated *.test.ts.

Recommended module layout:

apps/hono-api/src/modules/attendance
+-- attendance.routes.ts
+-- attendance.controller.ts
+-- attendance.service.ts
+-- attendance.repository.ts
+-- attendance.validator.ts
+-- attendance.policy.ts
+-- attendance.events.ts
+-- attendance.test.ts

Shared packages to add when implementation starts:

Build Roadmap

Phase 0: Architecture Foundation

• Pick one production API: Hono.
• Keep FastAPI/Rust/Nest as labs until a concrete service split is justified.
• Add product schema plan and module boundaries.
• Add shared contracts package.
• Add tenant/membership/role model.
• Add request ID, audit logging, rate limit, and secure headers.

Phase 1: Smart Attendance MVP

• Tenants, campuses, academic years, classes, sections, students, guardians.
• Auth and role-based access.
• QR token generation and scanner.
• Attendance sessions, marks, events, summaries.
• WhatsApp/SMS/email notification pipeline through outbox worker.
• Principal live dashboard.
• Parent mobile attendance feed.

Phase 2: Communication And Parent Trust

• Announcements.
• Teacher-parent conversations.
• Documents and signed permission slips.
• Event calendar and reminders.
• Emergency alert workflow with step-up authentication.

Phase 3: Academics

• Timetable.
• Homework.
• Assessments and marks.
• Report card generation.
• AI-drafted comments with teacher approval.
• Learning gap concept map.

Phase 4: Finance And Admissions

• Fee plans, invoices, payments, receipts.
• Payment gateway webhooks and reconciliation.
• Due reminders.
• Basic expense ledger.
• Admission inquiry CRM and next-best-action reminders.

Phase 5: AI-First Intelligence Layer

• Student intelligence profiles.
• Daily and Friday briefings.
• AI action approval queue.
• Parent chatbot with tenant-scoped RAG.
• Early warning system with reason codes and fairness review.
• Intervention playbook.

Phase 6: Scale And Enterprise Readiness

• Kafka/Redpanda if event volume requires it.
• Dedicated notification service.
• Dedicated AI service.
• Enterprise tenant isolation options.
• Data residency controls.
• Security review, penetration test, and compliance package.

Key Technical Decisions

Open Decisions Before Implementation

1. Standard ID format: migrate from current string CUID-style IDs to UUIDv7, or standardize CUID2 text IDs across all services.
2. WhatsApp provider: Meta WhatsApp Cloud API directly, Twilio, or a regional BSP.
3. Payment provider priority by market: Stripe, Razorpay, Paymob, Flutterwave, or local PSPs.
4. AI provider policy: OpenAI first with abstraction, or provider-neutral from day one.
5. Biometric attendance: explicitly out of MVP unless consent/legal review and a pilot demand it.
6. Data residency target for first market.
7. Whether to put generated report cards in object storage only or also store normalized snapshots.

Research References

• OWASP API Security Top 10 2023: https://owasp.org/API-Security/editions/2023/en/0x00-header/
• OWASP Application Security Verification Standard: https://owasp.org/www-project-application-security-verification-standard/
• OWASP CSRF Prevention Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Cross-Site_Request_Forgery_Prevention_Cheat_Sheet.html
• OWASP Session Management Cheat Sheet: https://cheatsheetseries.owasp.org/cheatsheets/Session_Management_Cheat_Sheet.html
• PostgreSQL Row Security Policies: https://www.postgresql.org/docs/17/ddl-rowsecurity.html
• Apache Kafka design and transactions: https://kafka.apache.org/41/design/design/
• Redis cache-aside documentation: https://redis.io/docs/latest/develop/use-cases/cache-aside/
• OpenTelemetry documentation: https://opentelemetry.io/docs/
• NIST SP 800-63B: https://pages.nist.gov/800-63-4/sp800-63b.html
• FTC COPPA statute and guidance: https://search.ftc.gov/legal-library/browse/statutes/childrens-online-privacy-protection-act and https://www.ftc.gov/business-guidance/resources/complying-coppa-frequently-asked-questions
• FERPA directory information guidance: https://studentprivacy.ed.gov/content/directory-information
• Hono secure headers middleware: https://hono.dev/docs/middleware/builtin/secure-headers
• Expo SecureStore documentation: https://docs.expo.dev/versions/latest/sdk/securestore/
• OpenAI Responses API and Agents SDK: https://developers.openai.com/api/reference/overview and https://developers.openai.com/api/docs/guides/agents
• pgvector: https://github.com/pgvector/pgvector