Production Roadmap

Purpose: This README defines how we will build Starter from the clean apps/nest-api NestJS app onward. It summarizes the full idea, the product philosophy, the backend/frontend/AI architecture, and the exact production roadmap. It is written so we can share it with other AI tools, collaborators, reviewers, and future funders before and during development.

1. Project Vision

Starter is not another school ERP, digital register, or dashboard.

Starter is an AI-native, policy-native, workflow-native operating system for schools.

Traditional school software usually does this:

User enters data
System stores data
User checks dashboard manually
User takes action manually

Starter should do this:

System understands school state
System detects missing work, risk, and policy violations
System creates tasks and reminders
AI drafts or assists the next action
Policy engine checks what is allowed
Human approval is required for important actions
System executes approved workflow
Audit log records everything

The long-term idea is bigger than school management. Starter is the first product in a future Community OS / Quality of Life OS approach, where the same architecture can later support education, health navigation, welfare, disaster preparedness, environment, youth development, and community service.

But the build focus now is strict:

Start with Starter.
Build slowly.
One production-quality vertical slice at a time.

2. Current Starting Point

The monorepo already exists and uses:

Bun workspaces
Turborepo
Next.js web app
Expo mobile app
NestJS API app
Docs app
Shared packages
CI/CD, Docker, security workflows, dev container, hooks

The backend production spine starts now from:

apps/nest-api

We intentionally start the NestJS backend clean and add concepts step by step.

3. Technical Decisions

Runtime and Tooling

Package manager: Bun
Workspace orchestration: Turborepo
Main backend framework: NestJS
Production backend runtime: Node-compatible Nest build first
Database: PostgreSQL
ORM/query layer: Drizzle ORM
Validation: Zod
API style first: REST
Frontend: Next.js
Mobile: Expo / React Native
Docs: docs app / Markdown

Bun stays important for fast local development and monorepo commands. NestJS remains the main backend framework because Starter needs structured modules, dependency injection, guards, interceptors, queues, WebSockets, auth, testing, and production architecture.

Drizzle is chosen because it is TypeScript-first, lightweight, SQL-friendly, and a good fit for PostgreSQL.

4. Core Product Philosophy

Everything we build should follow this principle:

Do not make teachers, admins, parents, or principals do more data entry.
Use software to reduce work, guide decisions, and execute safe workflows.

Starter must be:

AI-native
workflow-native
policy-native
task-first
privacy-first
offline-aware
local-language ready
audit-heavy
teacher-first
student-safe
parent-connected
integration-ready

5. What Makes Starter Different

A normal school ERP stores records:

students
teachers
attendance
fees
exams
reports

Starter adds operating intelligence:

policies
workflows
tasks
approvals
AI assistance
risk detection
parent communication
audit logs
notifications
integrations
offline workflows

One-line positioning:

Starter turns school operations from manual data entry into guided, automated, policy-safe workflows.

Stronger long-term positioning:

Starter is an execution layer for education and human development, starting with schools.

6. Main Engines

These engines are the heart of Starter. Domain modules like Students, Attendance, Fees, Homework, and Cleanliness plug into these engines.

6.1 Workflow Engine

Manages multi-step school processes.

Examples:

admission workflow
attendance follow-up workflow
homework review workflow
teacher leave workflow
cleanliness task workflow
student risk intervention workflow
fee reminder workflow

A workflow has:

definition
run
steps
owner
status
deadline
approval
escalation
audit events

6.2 Policy Engine

Turns school rules into executable logic.

Examples:

If student absent 3 days → create teacher follow-up task
If attendance below 80% → notify parent and principal
If cleaning issue unresolved 24h → escalate
If required admission document missing → block final approval

6.3 Task Engine

Every unresolved issue becomes a task.

Examples:

Call parent
Verify document
Review homework
Approve admission
Check classroom cleanliness
Follow up absent student
Assign substitute teacher

6.4 Notification Engine

Handles communication through:

in-app
email
SMS
WhatsApp later
push notifications later

6.5 AI Orchestration Engine

AI must assist, not control the system directly.

Safe AI flow:

AI reads allowed context
AI proposes action
Policy engine checks action
Permission engine checks action
Human approval happens if needed
Command handler executes action
Audit log records everything

AI should never directly update critical records without going through backend commands, policy checks, and audit logs.

6.6 Document Intelligence Engine

Used for admissions and admin work:

OCR
field extraction
document classification
missing document detection
form prefill
human verification

6.7 Integration Engine

For future external systems:

SMS provider
WhatsApp provider
email provider
payment gateway
object storage
biometric/RFID optional
camera AI optional
government export formats
calendar integrations

6.8 Audit and Governance Engine

Every important action must be traceable:

who did it
when
which organization/school
what changed
why
from which IP/device/request
whether AI was involved
whether approval was given

7. Product Modules

Core Records

Organizations
Schools
Users
Roles
Permissions
Students
Guardians
Teachers
Academic Years
Classes
Sections
Enrollments

School Operations

Attendance
Homework
Assessments
Timetable
Cleanliness
Facilities
Inventory
Transport later
Fees later

Intelligence

Student risk detection
Attendance pattern detection
Homework weakness detection
Teacher workload insight
Principal cockpit
AI summaries
AI message drafts

Communication

Parent updates
Announcements
Absence alerts
Meeting requests
Homework summaries
Fee reminders later

Governance

Audit logs
Consent records
AI usage logs
Approvals
Data retention
Tenant isolation
Security policies

8. Backend Architecture Direction

The backend starts in:

apps/nest-api

Initial structure:

apps/nest-api/src/
  main.ts
  app.module.ts
  app.setup.ts

  common/
    decorators/
    filters/
    guards/
    interceptors/
    middleware/
    pipes/
    types/
    utils/

  config/
    env.schema.ts
    app.config.ts
    database.config.ts
    config.module.ts
    app-config.service.ts

  database/
    database.module.ts
    database.provider.ts
    database.tokens.ts
    database.types.ts
    schema/
      index.ts

  modules/
    health/
    organizations/
    schools/
    users/
    auth/

Later structure:

modules/
  academic-structure/
  students/
  guardians/
  teachers/
  attendance/
  tasks/
  policies/
  workflows/
  notifications/
  audit-logs/
  ai/
  documents/
  integrations/
  realtime/

9. Backend Rules

Controller / Service / Repository

Controller = HTTP layer only
Service = business and use-case logic
Repository = database queries only
Schema/DTO = input validation and type shape
Guard = authentication/authorization
Interceptor = response/logging/metrics wrapping
Filter = error formatting
Module = feature boundary

Do not put business logic in controllers.

Do not put HTTP exceptions inside repositories unless there is a very strong reason.

Do not let AI or frontend directly mutate database records.

10. Import and Naming Rules

Use clear aliases later:

@common/*
@config/*
@database/*
@modules/*
@shared/*

File naming:

kebab-case files
PascalCase classes
camelCase variables/functions
is/has/can/should for booleans

Examples:

create-school.schema.ts
schools.controller.ts
schools.service.ts
schools.repository.ts
current-user.decorator.ts

11. API Response Standard

Success response:

{
  "success": true,
  "statusCode": 200,
  "requestId": "req_123",
  "timestamp": "2026-07-01T00:00:00.000Z",
  "data": {}
}

Error response:

{
  "success": false,
  "statusCode": 400,
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "requestId": "req_123",
  "timestamp": "2026-07-01T00:00:00.000Z",
  "path": "/api/v1/schools",
  "method": "POST",
  "errors": []
}

12. Multi-Tenant Rule

Every school belongs to an organization.

Most future data must be tenant-safe:

organizationId
schoolId when relevant
actorUserId when relevant

Repository methods should accept object params:

findById(params: {
  organizationId: string;
  schoolId: string;
})

Never query tenant-owned data without tenant scope.

Cross-tenant access should usually return 404, not 403, to avoid revealing that another tenant’s resource exists.

13. AI Safety Rule

AI can:

summarize
extract
draft
suggest
classify
flag
prepare

AI cannot directly:

create final student records
change grades
send sensitive messages
approve welfare/discipline actions
delete records
access all tenant data freely

AI actions must go through:

permission check
policy check
approval if required
command handler
audit log

14. Language and Localization

Starter should be multilingual from the design level.

Start with:

English
Urdu

Later possible:

Khowar
Shina
Burushaski
Wakhi

Do not hardcode user-facing text deeply into business logic. Prefer error codes and message keys where possible.

Example:

{
  "code": "STUDENT_NAME_REQUIRED",
  "messageKey": "students.errors.nameRequired"
}

15. Roadmap Overview

Phase 0 — Clean Nest Foundation

Goal: make the Nest API clean, predictable, and production-shaped.

Build:

health endpoint
global prefix /api/v1
URI versioning
config module
env validation
request ID middleware
response interceptor
exception filter
Zod validation pipe
basic app setup

Definition of done:

GET /api/v1/health works
consistent response shape
consistent error shape
invalid input returns validation error
app starts cleanly with Bun workspace command

Phase 1 — Database Foundation

Goal: connect PostgreSQL with Drizzle.

Build:

Docker Postgres or hosted Postgres
Drizzle install
DatabaseModule
schema folder
database provider
migration config
organizations table
schools table
users table basic

Definition of done:

migration runs
API can read/write organizations and schools
DB connection closes cleanly on shutdown

Phase 2 — Organization and School Slice

Goal: first real tenant slice.

Build:

OrganizationsModule
SchoolsModule
create organization
create school
list schools
get school
update school
soft delete school later

Definition of done:

POST organization works
POST school under organization works
school code unique per organization
tenant-safe reads
unit tests for service
basic e2e test

Phase 3 — Auth and Users

Goal: secure the system.

Build:

UsersModule
AuthModule
password hashing
login
JWT access token
refresh tokens
current user decorator
current organization decorator
JWT guard

Definition of done:

user can login
protected route requires token
invalid password fails safely
refresh token stored hashed
logout revokes session

Phase 4 — Roles and Permissions

Goal: role-based access control.

Build:

roles
permissions
user roles
role permissions
permissions guard
@Auth decorator
seed default permissions

Definition of done:

admin can create school
teacher cannot create school
permission denied returns 403
platform admin rules are explicit

Phase 5 — Academic Structure

Goal: define school academic setup.

Build:

academic years
classes
sections
teachers
teacher assignments

Definition of done:

school can create academic year
school can create class and section
teacher can be assigned to section
all reads tenant-safe

Phase 6 — Students and Enrollment

Goal: manage student records properly.

Build:

students
guardians basic later
student enrollments
student status
admission number uniqueness per school

Definition of done:

create student
update student
list students
enroll student into section and academic year
cannot enroll into another tenant’s school

Phase 7 — Attendance

Goal: first daily school workflow.

Build:

mark attendance
read section attendance
read student attendance history
attendance status counts
teacher assignment access check
parent notification event later

Definition of done:

teacher/admin can mark attendance
unassigned teacher cannot mark attendance
invalid student IDs rejected
attendance creates audit log
attendance event emitted

Phase 8 — Audit Logs

Goal: trust and traceability.

Build:

audit log table
audit log service
audit events for important actions
audit log listing with filters

Definition of done:

student creation audited
attendance marking audited
role changes audited
sensitive values not stored in audit metadata

Phase 9 — Tasks, Policies, and Workflows v1

Goal: make Starter more than CRUD.

Build:

tasks table
policy definitions simple
workflow runs simple
absence follow-up policy
cleaning issue task later

First workflow:

Student absent 3 consecutive days
→ create teacher follow-up task
→ notify teacher/principal later
→ audit log

Definition of done:

policy can trigger task
task has owner/status/deadline
workflow is traceable

Phase 10 — Notifications and Queue

Goal: background work.

Build:

Redis
BullMQ
notification queue
email/SMS adapter placeholder
parent absence message draft/send later

Definition of done:

job added to queue
worker processes job
failed jobs retry
worker logs job lifecycle

Phase 11 — AI Orchestration v1

Goal: safe AI layer.

Start with one feature:

Admission document assistant

Flow:

upload document
extract fields
prefill admission draft
admin verifies
policy checks required fields
approved command creates student

Definition of done:

AI output never directly writes final record
AI request logged
AI output validated
human approval required

Phase 12 — Web Admin v1

Goal: usable web interface.

Build:

login
organization/school setup
student list
student create form
academic setup
attendance screen
basic dashboard

UI principle:

task-first, not menu-first

Phase 13 — Teacher Mobile v1

Goal: daily teacher workflow.

Build:

login
my sections
mark attendance
offline draft later
student list
follow-up tasks

Phase 14 — Production Readiness

Build:

Swagger/OpenAPI
unit tests
e2e tests
Docker
CI
security hardening
rate limiting
structured logging
metrics
health checks

16. First Build Target Now

We start with Phase 0 only.

Do not build database yet if app setup is not clean.

First target:

GET /api/v1/health

Then add:

app.setup.ts
config module
env validation
request ID middleware
response interceptor
exception filter
Zod pipe

17. Development Commands

From repo root:

bun install
bun run preflight
bun --cwd=apps/nest-api run start:dev

If the app is clean:

curl http://localhost:3000/api/v1/health

Expected response:

{
  "success": true,
  "statusCode": 200,
  "requestId": "...",
  "timestamp": "...",
  "data": {
    "status": "ok",
    "service": "school-os-api"
  }
}

18. Definition of Done for Every Slice

A feature is not done until:

code works
validation exists
tenant safety considered
errors are clean
audit need checked
tests exist where needed
API shape is documented
no secrets in logs
no random architecture shortcuts

19. What Not To Do Yet

Do not start with:

AI agents
camera attendance
homework checker
Community OS
GraphQL
microservices
mobile offline sync
payment system
full dashboards

Those come later.

Start with the backend spine.

20. Other AI Review Prompt

Use this prompt when asking another AI to review the plan:

We are building Starter, an AI-native, policy-native, workflow-native operating system for schools. It is not a simple ERP or digital register. The backend starts with a clean NestJS app inside a Bun + Turborepo monorepo. We use PostgreSQL, Drizzle ORM, Zod validation, REST first, and production-grade architecture.

Please review this README as a senior backend/product architect. Focus on:
1. Whether the architecture is too much or too little for the first MVP.
2. Whether the build phases are in the correct order.
3. Whether AI safety, policy engine, workflow engine, and task engine are placed correctly.
4. What should be removed from the first 3 months.
5. What hidden risks exist in multi-tenant school software.
6. How to make this more fundable without overpromising.

Do not suggest generic ERP features unless they support the workflow/policy/AI-native vision.

21. References and Technical Anchors

NestJS documentation: https://docs.nestjs.com
NestJS CLI/workspaces: https://docs.nestjs.com/cli/monorepo
Bun workspaces: https://bun.com/docs/pm/workspaces
Turborepo docs: https://turborepo.com/docs
Drizzle PostgreSQL docs: https://orm.drizzle.team/docs/get-started/postgresql-new
Drizzle migrations: https://orm.drizzle.team/docs/migrations
PostgreSQL: https://www.postgresql.org/docs/
OWASP LLM / GenAI security: https://owasp.org/www-project-top-10-for-large-language-model-applications/
UNESCO AI in education: https://www.unesco.org/en/digital-education/artificial-intelligence

22. Final Build Principle

Slow is smooth.
Smooth is fast.

We will not rush into features.

We will build the spine first, then add intelligence layer by layer.

The first practical milestone is:

Clean Nest API foundation with /api/v1/health and production response/error structure.

Production Roadmap

On this page