AcademiaOS

AcademiaOS is a comprehensive full-stack platform designed to digitize the administrative and academic operations of educational institutions.

Developed during my academic internship at WalkersHive, this project was an exercise in System Architecture rather than just feature building. Before writing a single line of business logic, I engineered a reusable Next.js Enterprise Starter. AcademiaOS was built on top of this foundation, serving as a real-world stress test that allowed me to refine the starter's architecture and internal documentation side-by-side with the product development.

Scope & Intent

AcademiaOS was intentionally designed as an architecture-heavy system. The goal was to explore schema-first APIs, async processing, and frontend-backend contract enforcement in a real-world environment.

For smaller applications (e.g., a CRUD app or simple dashboard), I would avoid tools like Redis, Celery, and code generation to keep the system simple and maintainable. However, AcademiaOS presented an opportunity to experiment with these advanced patterns meaningfully.

🏗️ System Architecture: The "Schema-First" Approach

One of the biggest challenges in full-stack development is "API Drift"—where the frontend code falls out of sync with the backend response. To solve this, I implemented a strict Schema-First Workflow:

1. Backend Authority: The FastAPI backend generates an openapi.json spec based on Pydantic models.
2. Automated Generation: On the frontend, I configured Orval to read this spec and auto-generate:

• TypeScript Interfaces: Ensuring 100% type matching with the database models.
• React Query Hooks: Fully typed hooks like useGetFaculties or useCreateNotice.
• Zod Schemas: For runtime validation in forms.

The Result: A breakage in the backend API immediately causes a build error in the frontend, preventing runtime bugs before they happen.

---

💻 Frontend Engineering (Next.js)

Inherited from my Enterprise Starter, I used a Hybrid 3-Layer Design to decouple business logic from the framework:

1. Domain-Driven Structure

• Layer 1 (Features): Environment-agnostic domain logic (e.g., src/features/auth). Contains "smart" components and business hooks.
• Layer 2 (App-Pages): Visual assembly layer. Composes features into layouts without containing routing logic.
• Layer 3 (App): The Next.js Orchestrator. Handles routing, SEO, and server-side data fetching.

2. Performance Strategy

To eliminate "Loading..." spinners and Layout Shifts (CLS):

• Server Prefetching: I use TanStack Query on the Node.js server (page.tsx) to fetch data and dehydrate the cache.
• Instant Hydration: When the Client Component mounts, it finds the data already in the cache, resulting in an instant initial paint.
• Skeletons: For client-side interactions, I built strict skeleton components that reserve exact pixel dimensions to maintain visual stability.

3. Advanced State Management

• URL as State: Replaced useState with Nuqs to sync filters and pagination with the URL (e.g., ?tab=pending&page=2), making every dashboard view shareable.
• Auth Sync: Implemented a useAuthGuard hook that checks a non-sensitive logged_in cookie flag for immediate client-side redirects, allowing the UI to react instantly while the secure HttpOnly cookie handles the actual session.

---

⚡ Backend Engineering (FastAPI)

The backend was designed for high concurrency and fault tolerance using Python 3.10+ and SQLModel.

1. Async & Non-Blocking Design

Heavy operations, such as sending registration emails or generating reports, are offloaded to Celery Workers backed by Redis Cloud. This ensures the API responds immediately to the user while the heavy lifting happens in the background.

2. Intelligent Caching

I implemented a Cache-Aside pattern for high-traffic endpoints like Notices and Routines.

• Read Path: Check Redis -> If Miss, Query DB -> Write to Redis -> Return.
• Write Path: DB Update -> Invalidate specific Redis keys to ensure consistency.

3. Context-Aware AI Assistant

Instead of a generic chatbot, I integrated Google Gemini as a navigational aide.

• Context Injection: The backend dynamically builds a context string based on the user's role (e.g., "User is a Student, enrolled in BCA 4th Sem").
• Utility: If a student asks "Where is my routine?", the AI generates a direct link to their specific batch's routine page, effectively acting as an intelligent site map.

---

🧩 Developer Experience (DX) & Tooling

To ensure the codebase remains maintainable, I integrated the DX tools from my starter kit directly into the project:

• Integrated Documentation Engine: I built a custom MDX loader (using remark/rehype) to render the starter's architectural guides (/starter-docs) directly inside the running application, ensuring new developers have context immediately.
• Contentlayer Integration: Configured Contentlayer to handle future user-facing documentation and blog content.
• Mock Service Worker (MSW): Configured a robust mocking layer (dev:mock), allowing frontend development to continue even if the backend is down.
• Strict Zod Env Validation: The build pipeline fails immediately if environment variables are missing or malformed.

🛠️ Tech Stack Summary

Domain	Technologies
Frontend	Next.js 16 (App Router), TypeScript 5, Tailwind v4, Shadcn/UI
State	TanStack Query v5, Nuqs (URL State)
Backend	FastAPI, SQLModel (SQLAlchemy), Pydantic
Database	PostgreSQL (Neon.tech), Redis (Redis Cloud)
Async/Job	Celery, Redis
Tools	Orval (Codegen), Contentlayer, Docker