Aatmanova — School Management & AMC Portal

Table of Contents

• The Challenge
• Architecture & Solution
• Tech Stack
• Key Engineering Decisions
• Deep-Dive: Maintenance Playbook
• Deployment

The Challenge

Modern Indian schools operate under complex requirements, managing grading, statutory reporting, hostel allocation, fees, and communication. Admin staff often juggle multiple disconnected systems and paper registers, leading to data fragmentation and inefficiencies.

However, existing educational packages fail under real operational load:

• Fragile Codebase Structure: A change in a minor feature can break the entire database, causing system-wide outages.
• Offline Failure Risks: Intermittent connectivity in rural Indian areas often results in data loss for daily attendance and grading records.
• PII Leakage Hazards: School platforms collect vast amounts of sensitive student and parent data, including Aadhaar, health status, and bank records. Under the Digital Personal Data Protection (PDPP) Act 2023, holding this data without explicit parent consent and audit pathways carries substantial legal risk.
• Concurrent Transaction Lockups: Bulk grading submissions or simultaneous morning attendance recordings from 50 teachers cause database deadlocks, losing records.

The requirement: Build a highly secure school ERP system managed under a professional Annual Maintenance Contract (AMC). The system must feature a modular monolith architecture, handle CBSE/ICSE multi-board regulations, guarantee high data availability using an offline-first outbox sync system, and meet Indian PDPP data compliance standards.

Architecture & Solution

To ensure operational resilience, the ERP is engineered as an event-driven Modular Monolith, providing complete domain isolation for all 16 modules while utilizing a Redis outbox synchronization pattern.

Module Isolation Boundary

Every module acts as a self-contained vertical slice, complete with its own controllers, services, database migrations, and tests. Modules communicate exclusively via asynchronous event buses, ensuring that if one module undergoes updates or experiences issues, all other 15 modules continue to run without interruption.

Tech Stack

Key Engineering Decisions

1. Modular Monolith vs Microservices (Non-Technical Maintainability)

• Why over Microservices: Microservices introduce huge infrastructure costs and networking overhead, which is not viable for standard school budgets. A modular monolith offers perfect domain isolation in a single deployment package.
• Implementation: Custom namespace separation where every domain (e.g., Finance, Attendance) contains all its logic.
• Result: Touched features follow the 5-file rule (changes affect ≤ 5 files in the same directory). The entire system can be maintained by a single technical operation lead.

2. Optimistic Locking on Concurrent Writes (System Stability)

• Why over row-level locking: Lock queues for bulk attendance (1,200 entries at once) tie up database threads, causing page response timeouts.
• Implementation: Implemented a version-based lock trait on database updates.

  // HasOptimisticLock trait — version-based concurrent write protection
  public function updateWithLock(array $data): bool {
      return $this->where('id', $this->id)
                  ->where('version', $this->version)
                  ->update(array_merge($data, ['version' => $this->version + 1])) > 0;
  }

• Result: Solves concurrent submission deadlocks. Stale updates are caught and rejected cleanly with a 409 Conflict without lock queues.

3. Dynamic Batch Routing (SLA Integrity)

• Why over direct job dispatch: Users executing small actions want instant UI feedback, while large batch payroll processes must run asynchronously to prevent gateway timeouts.
• Implementation: Configured dynamic routing thresholds. Operations automatically switch from inline synchronous execution to Redis background worker queues if the payload size exceeds 10 records.
• Result: Keeps the user interface highly responsive. Zero connection timeout failures on large administrative exports.

4. Student Withdrawal Transactional SAGA (Data Integrity)

• Why over single-table deletion: Safe student deletion requires cleaning references across Hostel, Transport, Library, and Finance modules. If one fails, the database is left in a corrupted state.
• Implementation: Implemented the SAGA transactional outbox pattern. All associated events are written to an append-only domain_events table in the same transaction, ensuring eventual consistency.
• Result: Guaranteed clean, complete removals. Complete data cleanup is achieved even if processes crash mid-operation.

5. PII Protection at DTO Layer (PDPP 2023 Compliance)

• Why over standard API filters: If database queries pull raw values, any internal logging tool or console debug could accidentally leak sensitive parent and student data.
• Implementation: Sensitive fields (like Aadhaar, phone numbers, and health records) are masked at the Data Transfer Object (DTO) layer before reaching the business services, checking user permissions dynamically.
• Result: Complete data privacy. Standard personnel see only masked entries (XXXX-XXXX-1234), with full data visible only to audited administrators holding explicit permissions.

Deep-Dive: Maintenance Playbook

Operations are executed via a strict daily, weekly, monthly, and quarterly schedule:

Daily (Automated)

• Vulnerability Checks: Daily automated package scanner checks system libraries for vulnerabilities.
• Uptime Monitoring: External ping monitors check system status every 5 minutes. Down times send instant alerts to the operations team.
• Offsite Backups: Daily database and media files are backed up, encrypted, and uploaded to a secure, remote cloud bucket.

Weekly

• Sync Logs Verification: Audit the offline outbox sync logs to confirm that all mutations from low-connectivity environments successfully resolved.
• System Resource Check: Review database connection pools, memory consumption trends, and queue delay metrics.
• Staging Sync: Sync the staging sandbox environment with the latest production system schemas to maintain test accuracy.

Monthly

• Staging Package Tests: Perform Laravel core upgrades, package security patches, and styling changes on the staging environment.
• Compatibility Review: Check system debug logs and console outputs on staging to catch any PHP warning or script errors.
• Production Rollout: Apply updates to the production server during planned maintenance windows (01:00-03:00 IST).
• Lighthouse Performance Audit: Monthly speed, accessibility, and Core Web Vitals audit reports delivered to the school administration.

Quarterly

• Deep Penetration Testing: Run manual and tool-assisted security tests to audit API authorization rules and check for privilege escalation risks.
• PDPP Compliance Check: Review parent data consent logs, verify data deletion records, and check that older databases are cleared as scheduled.
• Recovery Restore Dry-Run: Restore a production backup to an isolated sandbox server to verify recovery times and data integrity.

Support Model & SLA (Quick Inquiry Response)

Deployment

Quick Start

To spin up a local development environment matching production parameters:

# Clone the repository structure
git clone https://github.com/bhargab-pratim-sarma/aatmanova-amc.git && cd aatmanova-amc

# Setup environment parameters
cp .env.example .env

# Spin up services (PostgreSQL, Redis) via Docker Compose
docker compose up -d

# Run database migrations and seed system schemas
docker compose exec app php artisan migrate --seed

Production Stack

Nginx Reverse Proxy → PHP-FPM 8.3 FPM → Laravel 11
PostgreSQL 16 (Primary + Read Replica)
Redis Cache & Queue Store (Supervisor managed)
HashiCorp Vault Secrets Manager

Deployment Checklist

• [ ] Staging compatibility checks pass (zero console errors, zero runtime warnings).
• [ ] Complete database backup uploaded to cloud storage.
• [ ] DB migrations deployed using php artisan migrate --force.
• [ ] System cache files cleared and compiled templates warmed up.
• [ ] Automated health checks run on all dynamic routes.
• [ ] Post-deploy form validation and email notification checks pass.
• [ ] Incognito browser testing completed for data protection cookies.

*This case study documents our operational execution of a professional Annual Maintenance Contract (AMC). All practices strictly align with data privacy, security, and staging-first workflows suitable for mission-critical school deployments.*