Micro-Frontend & Microservices Architecture
🎯 Architecture Philosophy
"Right-sized services, not micro for micro's sake"
EduPulse follows a pragmatic microservices approach - we split services based on:
- Team ownership - Who maintains it?
- Deployment frequency - How often does it change?
- Scaling needs - Does it need independent scaling?
- Technology requirements - Does it need a different tech stack?
🖥️ Micro-Frontend Architecture
Why Micro-Frontends?
| Benefit | EduPulse Context |
|---|---|
| Independent Deployments | Update Fee module without touching SIS |
| Team Autonomy | HR team owns HR MFE completely |
| Technology Flexibility | AI features can use different libs |
| Scalability | Heavy dashboards load independently |
MFE Strategy: Module Federation
We use Webpack Module Federation with Next.js for:
- Runtime integration (not build-time)
- Shared dependencies (React, UI library)
- Independent versioning
🏗️ Shell & Child MFE Breakdown
Shell Application (Host)
The Shell MFE is the orchestrator that handles cross-cutting concerns.
┌─────────────────────────────────────────────────────────────────────────────┐
│ SHELL MFE (Host) │
│ edupulse-shell.vercel.app │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ SHELL RESPONSIBILITIES │ │
│ ├─────────────────────────────────────────────────────── ──────────────┤ │
│ │ • Authentication & Session Management │ │
│ │ • Global Navigation (Sidebar, Header, Breadcrumbs) │ │
│ │ • Tenant Context Provider │ │
│ │ • Theme Provider (Light/Dark mode) │ │
│ │ • Global Error Boundary │ │
│ │ • Notification System (Toast, Alerts) │ │
│ │ • Permission Context (RBAC) │ │
│ │ • Analytics Wrapper │ │
│ │ • PWA Service Worker │ │
│ │ • Global Search │ │
│ │ • User Profile & Settings │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ SHELL LAYOUT │ │
│ │ ┌──────────┬───────────────────────────────────────────────────┐ │ │
│ │ │ │ Header (User, Notifications, School Switcher) │ │ │
│ │ │ ├───────────────────────────────────────────────────┤ │ │
│ │ │ Sidebar │ │ │ │
│ │ │ (Nav) │ REMOTE MFE CONTAINER │ │ │
│ │ │ │ (Dynamic Loading Zone) │ │ │
│ │ │ │ │ │ │
│ │ │ │ │ │ │
│ │ └──────────┴───────────────────────────────────────────────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Shell MFE Tech Stack
// shell/package.json
{
"name": "@edupulse/shell",
"dependencies": {
"next": "15.x",
"@module-federation/nextjs-mf": "^8.x",
"@tanstack/react-query": "^5.x",
"zustand": "^5.x", // Global state
"@edupulse/ui": "workspace:*", // Shared UI library
"next-auth": "^5.x" // Authentication
}
}
Shell Shared Exports
// shell/src/shared/index.ts - Exposed to all MFEs
export { AuthProvider, useAuth } from './auth';
export { TenantProvider, useTenant } from './tenant';
export { ThemeProvider, useTheme } from './theme';
export { PermissionGate, usePermissions } from './permissions';
export { useNotification } from './notifications';
export { apiClient } from './api-client';
export { queryClient } from './query-client';
Child MFE Breakdown
We have 6 Child MFEs organized by domain and team ownership:
┌─────────────────────────────────────────────────────────────────────────────┐
│ CHILD MFEs (Remotes) │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ MFE-CORE │ │ MFE-ACADEMIC │ │ MFE-FINANCE │ │
│ │ (SIS + Admin) │ │ (Learning) │ │ (Fees + HR) │ │
│ ├─────────────────┤ ├─────────────────┤ ├─────────────────┤ │
│ │ • Dashboard │ │ • Timetable │ │ • Fee Config │ │
│ │ • Students │ │ • Attendance │ │ • Invoices │ │
│ │ • Admissions │ │ • Gradebook │ │ • Payments │ │
│ │ • Classes │ │ • Exam Results │ │ • Reports │ │
│ │ • Documents │ │ • Report Cards │ │ • HR/Staff │ │
│ │ • Settings │ │ • Assignments │ │ • Payroll │ │
│ │ │ │ • Curriculum │ │ • Leave Mgmt │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ MFE-AI │ │ MFE-PORTAL │ │ MFE-OPS │ │
│ │ (AI Features) │ │ (Public/User) │ │ (Operations) │ │
│ ├─────────────────┤ ├─────────────────┤ ├─────────────────┤ │
│ │ • AI Tutor │ │ • Parent Portal │ │ • Transport │ │
│ │ • Doubt Snap │ │ • Student Portal│ │ • Assets/Lab │ │
│ │ • Exam Predict │ │ • Teacher Portal│ │ • Library │ │
│ │ • Question Gen │ │ • Admission Form│ │ • Wellness │ │
│ │ • Analytics │ │ • Fee Payment │ │ • Events │ │
│ │ • Chatbots │ │ • Alumni │ │ • Notices │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
MFE Details
1. MFE-Core (SIS & Administration)
| Attribute | Value |
|---|---|
| Package | @edupulse/mfe-core |
| Team | Core Platform |
| EPICs | EPIC-1, EPIC-2, EPIC-3 |
| Deployment | Daily |
| Size | Large (~150 components) |
Modules:
/dashboard- Admin dashboard, widgets, quick actions/students- Student CRUD, search, bulk actions/admissions- Inquiry, applications, enrollment/classes- Class/section management, promotions/documents- Document management, verification/settings- School settings, academic year, configurations
2. MFE-Academic (Teaching & Learning)
| Attribute | Value |
|---|---|
| Package | @edupulse/mfe-academic |
| Team | Academic Team |
| EPICs | EPIC-7 |
| Deployment | Weekly |
| Size | Medium (~80 components) |
Modules:
/timetable- Schedule builder, room allocation/attendance- Mark attendance, reports, biometric sync/gradebook- Marks entry, grade calculation/exams- Exam scheduling, seating, hall tickets/report-cards- Generate, customize, print/assignments- Create, submit, grade
3. MFE-Finance (Fees & HR)
| Attribute | Value |
|---|---|
| Package | @edupulse/mfe-finance |
| Team | Finance Team |
| EPICs | EPIC-4, EPIC-5 |
| Deployment | Weekly |
| Size | Medium (~100 components) |
Modules:
/fees- Fee structure, invoices, collections/payments- Online payments, receipts/reports- Financial reports, outstanding dues/hr- Staff management, profiles/payroll- Salary processing, payslips/leave- Leave applications, approvals
4. MFE-AI (AI-Powered Features)
| Attribute | Value |
|---|---|
| Package | @edupulse/mfe-ai |
| Team | AI/ML Team |
| EPICs | EPIC-6, EPIC-8, EPIC-9 |
| Deployment | Bi-weekly |
| Size | Medium (~60 components) |
| Special | Uses Python backend |
Modules:
/tutor- AI tutoring chat interface/doubt-snap- Camera capture, OCR, solution/predictor- Exam prediction dashboard/question-gen- AI question paper generator/analytics- AI-powered insights/chatbots- Admission, support chatbots
5. MFE-Portal (User-Facing Portals)
| Attribute | Value |
|---|---|
| Package | @edupulse/mfe-portal |
| Team | Product Team |
| EPICs | EPIC-3, EPIC-4, EPIC-13 |
| Deployment | Weekly |
| Size | Medium (~70 components) |
| Special | Public pages, SEO optimized |
Modules:
/parent- Parent dashboard, child tracking/student- Student self-service/teacher- Teacher dashboard, quick actions/admission- Public admission form/pay- Fee payment gateway/alumni- Alumni network, events
6. MFE-Ops (Operations)
| Attribute | Value |
|---|---|
| Package | @edupulse/mfe-ops |
| Team | Operations Team |
| EPICs | EPIC-10, EPIC-11, EPIC-12 |
| Deployment | Monthly |
| Size | Small (~50 components) |
Modules:
/transport- Route management, tracking/assets- Inventory, lab equipment/library- Book management, issue/return/wellness- Health records, counseling/events- Event calendar, registrations/notices- Notice board, circulars
MFE Routing Strategy
// shell/src/app/layout.tsx
const MFE_ROUTES = {
// MFE-Core
'/dashboard': 'mfe-core/Dashboard',
'/students': 'mfe-core/Students',
'/admissions': 'mfe-core/Admissions',
'/classes': 'mfe-core/Classes',
// MFE-Academic
'/timetable': 'mfe-academic/Timetable',
'/attendance': 'mfe-academic/Attendance',
'/gradebook': 'mfe-academic/Gradebook',
'/exams': 'mfe-academic/Exams',
// MFE-Finance
'/fees': 'mfe-finance/Fees',
'/payments': 'mfe-finance/Payments',
'/hr': 'mfe-finance/HR',
'/payroll': 'mfe-finance/Payroll',
// MFE-AI
'/ai-tutor': 'mfe-ai/Tutor',
'/doubt-snap': 'mfe-ai/DoubtSnap',
'/predictor': 'mfe-ai/Predictor',
// MFE-Portal
'/parent-portal': 'mfe-portal/Parent',
'/student-portal': 'mfe-portal/Student',
'/teacher-portal': 'mfe-portal/Teacher',
// MFE-Ops
'/transport': 'mfe-ops/Transport',
'/assets': 'mfe-ops/Assets',
'/library': 'mfe-ops/Library',
};
Shared UI Library
All MFEs share a common UI library:
// packages/ui/src/index.ts
export * from './components/Button';
export * from './components/Input';
export * from './components/Table';
export * from './components/DataGrid';
export * from './components/Form';
export * from './components/Modal';
export * from './components/Card';
export * from './components/Charts';
// ... 50+ components
export * from './layouts/PageLayout';
export * from './layouts/FormLayout';
export * from './layouts/ListLayout';
export * from './hooks/useDebounce';
export * from './hooks/useInfiniteScroll';
export * from './hooks/useMediaQuery';
🔧 Microservices Architecture
Service Count Strategy
"6-8 services is the sweet spot for a team of 8-12 developers"
| Approach | Services | Pros | Cons |
|---|---|---|---|
| Monolith | 1 | Simple | Hard to scale, deploy |
| Mini-services | 3-4 | Easy to manage | Limited flexibility |
| Right-sized ✓ | 6-8 | Balanced | Our choice |
| Micro | 15+ | Very flexible | Complex, overhead |
EduPulse Service Breakdown: 7 Services
┌─────────────────────────────────────────────────────────────────────────────┐
│ MICROSERVICES ARCHITECTURE │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ │
│ │ API GATEWAY │ │
│ │ (Kong / AWS) │ │
│ └────────┬────────┘ │
│ │ │
│ ┌──────────────────────────┼──────────────────────────┐ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌─────────────────┐ ┌── ───────────────┐ ┌─────────────────┐ │
│ │ AUTH SERVICE │ │ SIS SERVICE │ │ FINANCE SERVICE │ │
│ │ (Node.js) │ │ (Node.js) │ │ (Node.js) │ │
│ ├─────────────────┤ ├─────────────────┤ ├─────────────────┤ │
│ │ • Cognito │ │ • Students │ │ • Fee Config │ │
│ │ • JWT/Sessions │ │ • Admissions │ │ • Invoices │ │
│ │ • RBAC │ │ • Classes │ │ • Reports │ │
│ │ • Audit Logs │ │ • Documents │ │ • HR/Staff │ │
│ │ • Encryption │ │ • Promotions │ │ • Leave │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ ACADEMIC SERVICE│ │ AI SERVICE │ │ OPS SERVICE │ │
│ │ (Node.js) │ │ (Python) │ │ (Node.js) │ │
│ ├─────────────────┤ ├─────────────────┤ ├─────────────────┤ │
│ │ • Timetable │ │ • AI Tutor │ │ • Transport │ │
│ │ • Attendance │ │ • Exam Predict │ │ • Assets │ │
│ │ • Gradebook │ │ • Doubt Snap │ │ • Library │ │
│ │ • Exams │ │ • Question Gen │ │ • Wellness │ │
│ │ • Report Cards │ │ • Analytics │ │ • Events │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │
│ ┌─────────────────┐ │
│ │ ENGINE SERVICE │ │
│ │ (Go) │ │
│ ├─────────────────┤ │
│ │ • Payment Proc │ │
│ │ • Finance Engine│ │
│ │ • Attendance Eng│ │
│ │ • Notifications │ │
│ │ • Real-time │ │
│ └─────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Service Details
Service 1: Auth Service (Node.js)
| Attribute | Value |
|---|---|
| Language | Node.js/TypeScript |
| Framework | NestJS |
| Database | PostgreSQL (shared) |
| EPICs | EPIC-2 |
| Team | Platform |
Responsibilities:
- Cognito integration
- JWT token management
- Session management
- RBAC/Permissions
- Audit logging
- Data encryption/decryption service
- DPDPA compliance
API Prefix: /api/v1/auth/*
Service 2: SIS Service (Node.js)
| Attribute | Value |
|---|---|
| Language | Node.js/TypeScript |
| Framework | NestJS |
| Database | PostgreSQL |
| EPICs | EPIC-3 |
| Team | Core |
Responsibilities:
- Student management
- Guardian management
- Admission workflow
- Class/Section management
- Document management
- Transfer certificates
- Promotion/Transfer
API Prefix: /api/v1/sis/*
Service 3: Finance Service (Node.js)
| Attribute | Value |
|---|---|
| Language | Node.js/TypeScript |
| Framework | NestJS |
| Database | PostgreSQL |
| EPICs | EPIC-4, EPIC-5 |
| Team | Finance |
Responsibilities:
- Fee structure configuration
- Invoice generation
- Payment tracking
- Financial reports
- HR/Staff management
- Leave management
- Payroll configuration
API Prefix: /api/v1/finance/*, /api/v1/hr/*
Service 4: Academic Service (Node.js)
| Attribute | Value |
|---|---|
| Language | Node.js/TypeScript |
| Framework | NestJS |
| Database | PostgreSQL |
| EPICs | EPIC-7 |
| Team | Academic |
Responsibilities:
- Timetable management
- Attendance (mark, reports)
- Gradebook
- Exam management
- Report card generation
- Curriculum management
API Prefix: /api/v1/academic/*
Service 5: AI Service (Python)
| Attribute | Value |
|---|---|
| Language | Python |
| Framework | FastAPI |
| Database | PostgreSQL + Qdrant |
| EPICs | EPIC-6, EPIC-8, EPIC-9 |
| Team | AI/ML |
Responsibilities:
- AI Tutor conversations
- Doubt Snap (OCR + solution)
- Board Exam prediction
- Question generation
- AI-powered analytics
- RAG pipelines
- Claude API integration
API Prefix: /api/v1/ai/*
Service 6: Ops Service (Node.js)
| Attribute | Value |
|---|---|
| Language | Node.js/TypeScript |
| Framework | NestJS |
| Database | PostgreSQL |
| EPICs | EPIC-10, EPIC-11, EPIC-12, EPIC-13 |
| Team | Operations |
Responsibilities:
- Transport management
- Asset/Inventory management
- Library management
- Wellness/Health records
- Event management
- Alumni network
API Prefix: /api/v1/ops/*
Service 7: Engine Service (Go)
| Attribute | Value |
|---|---|
| Language | Go |
| Framework | Gin |
| Database | PostgreSQL |
| EPICs | EPIC-4, EPIC-5 (critical paths) |
| Team | Platform |
Responsibilities:
- Payment gateway processing
- Double-entry finance engine
- Attendance engine (biometric sync)
- Notification dispatcher
- Real-time sync (WebSocket)
- Background job processing
- Event sourcing
API Prefix: /api/v1/engine/*
Service Communication
┌─────────────────────────────────────────────────────────────────────────────┐
│ SERVICE COMMUNICATION PATTERNS │
├───────────────────────────────────────────────────────────────── ────────────┤
│ │
│ SYNCHRONOUS (REST/gRPC) │
│ ──────────────────────── │
│ • User-facing API calls │
│ • Auth validation │
│ • Real-time data fetches │
│ │
│ Frontend ──REST──► Node.js Services ──gRPC──► Go Engine │
│ ──REST──► Python AI │
│ │
│ ASYNCHRONOUS (Message Queue) │
│ ──────────────────────────── │
│ • Notifications (SMS, Email, Push) │
│ • Bulk operations │
│ • AI processing │
│ • Event sourcing │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ MESSAGE QUEUE (Redis + NATS) │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ ▲ ▲ ▲ ▲ ▲ │
│ │ │ │ │ │ │
│ ┌──┴──┐ ┌───┴───┐ ┌───┴───┐ ┌───┴───┐ ┌───┴───┐ │
│ │Auth │ │ SIS │ │Finance│ │ AI │ │Engine │ │
│ └─────┘ └───────┘ └───────┘ └───────┘ └───────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
Database Strategy
┌─────────────────────────────────────────────────────────────────────────────┐
│ DATABASE STRATEGY │
├─────────────────────────────────────────────────────────────────────────────┤
│ │
│ SHARED DATABASE (Phase 1: 0-100K users) │
│ ──────────────────────────────────────── │
│ • Single PostgreSQL instance │
│ • Schema-per-tenant (tenant_id in every table) │
│ • Simpler operations, easier debugging │
│ │
│ ┌─────────────────────────────────────────────────────────────────────┐ │
│ │ PostgreSQL (Single Instance) │ │
│ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │
│ │ │ auth │ │ sis │ │ finance │ │academic │ │ ops │ │ │
│ │ │ schema │ │ schema │ │ schema │ │ schema │ │ schema │ │ │
│ │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │
│ └─────────────────────────────────────────────────────────────────────┘ │
│ │
│ DATABASE-PER-SERVICE (Phase 2: 100K+ users) │
│ ─────────────────────────────────────────── │
│ • Separate databases for critical services │
│ • Finance gets dedicated instance │
│ • AI gets dedicated instance + Qdrant │
│ │
└─────────────────────────────────────────────────────────────────────────────┘
📁 Repository Structure
Monorepo with Turborepo
edupulse/
├── apps/
│ ├── shell/ # Shell MFE (Host)
│ ├── mfe-core/ # Core MFE
│ ├── mfe-academic/ # Academic MFE
│ ├── mfe-finance/ # Finance MFE
│ ├── mfe-ai/ # AI MFE
│ ├── mfe-portal/ # Portal MFE
│ └── mfe-ops/ # Ops MFE
│
├── services/
│ ├── auth-service/ # Node.js Auth
│ ├── sis-service/ # Node.js SIS
│ ├── finance-service/ # Node.js Finance
│ ├── academic-service/ # Node.js Academic
│ ├── ai-service/ # Python AI
│ ├── ops-service/ # Node.js Ops
│ └── engine-service/ # Go Engine
│
├── packages/
│ ├── ui/ # Shared UI components
│ ├── types/ # Shared TypeScript types
│ ├── utils/ # Shared utilities
│ ├── config/ # Shared configurations
│ └── eslint-config/ # Shared ESLint
│
├── infrastructure/
│ ├── cdk/ # AWS CDK
│ ├── docker/ # Docker configs
│ └── k8s/ # Kubernetes manifests
│
├── docs/ # Documentation
├── turbo.json # Turborepo config
├── pnpm-workspace.yaml # PNPM workspaces
└── package.json # Root package
🗺️ MFE to Service Mapping
| MFE | Primary Services | Secondary Services |
|---|---|---|
| Shell | Auth | All (for context) |
| MFE-Core | SIS, Auth | Engine |
| MFE-Academic | Academic | SIS |
| MFE-Finance | Finance | Engine, Auth |
| MFE-AI | AI | SIS, Academic |
| MFE-Portal | SIS, Finance | Auth |
| MFE-Ops | Ops | SIS |
📊 Summary
MFE Summary (6 Child + 1 Shell)
| MFE | Team | Size | Deploy Freq |
|---|---|---|---|
| Shell | Platform | 30 components | Weekly |
| MFE-Core | Core | 150 components | Daily |
| MFE-Academic | Academic | 80 components | Weekly |
| MFE-Finance | Finance | 100 components | Weekly |
| MFE-AI | AI/ML | 60 components | Bi-weekly |
| MFE-Portal | Product | 70 components | Weekly |
| MFE-Ops | Operations | 50 components | Monthly |
Service Summary (7 Services)
| Service | Language | Team | EPICs |
|---|---|---|---|
| Auth | Node.js | Platform | 2 |
| SIS | Node.js | Core | 3 |
| Finance | Node.js | Finance | 4, 5 |
| Academic | Node.js | Academic | 7 |
| AI | Python | AI/ML | 6, 8, 9 |
| Ops | Node.js | Operations | 10-13 |
| Engine | Go | Platform | 4, 5 (critical) |