DEV Community: Hamid Karimi

I Built an Open-Source School Management System API — SchoolOS

Hamid Karimi — Mon, 23 Mar 2026 10:28:11 +0000

What is SchoolOS?

SchoolOS is a fully production-ready School Management Information System (MIS) REST API built with Node.js, Express, TypeScript, and MongoDB. It covers everything a school needs to manage its operations through a clean, well-structured API.

The project is fully open-source under the MIT license, anyone can use it, extend it, or contribute to it.

Tech Stack

Runtime: Node.js
Framework: Express.js
Language: TypeScript
Database: MongoDB + Mongoose
Validation: Zod
Authentication: JWT (Access + Refresh tokens with session management)

What's included?

SchoolOS ships with 12 fully tested modules:

Students — CRUD, filtering, search, pagination
Teachers — CRUD with subject and qualification tracking
Classes — Class creation, student enrollment, capacity management
Timetable — Weekly scheduling with teacher conflict detection
Attendance — Single and bulk recording, student summary reports
Exams — Exam scheduling with status tracking
Grades — Auto grade calculation (A+/A/B/C/D/F), bulk entry, summaries
Fees — Payment recording, overdue tracking, student summaries
Announcements — Audience-targeted (all, teachers, students, parents)
Messages — Inbox, sent, unread count, read receipts
Library — Book catalog, borrow/return with availability control
HR — Staff management, contracts, salary summaries

Architecture

The project follows a clean flat layered architecture. Every feature is spread across exactly 5 files:

models/       → Mongoose schema and TypeScript interface
validators/   → Zod schemas for request validation
services/     → Business logic (database operations)
controllers/  → HTTP handlers (thin, no business logic)
routes/       → Express router with middleware applied

The single rule: controllers stay thin. All database queries and business logic belong in services.

Authentication

Authentication is powered by a custom JWT system with:

Access token (short-lived, sent in Authorization header)
Refresh token (long-lived, stored in httpOnly cookie)
Session management with device tracking
Role-based access control (admin, teacher, student, parent)

Response Format

All endpoints follow a consistent response structure:

{
  "success": true,
  "data": {},
  "message": "Operation successful"
}

Getting Started

git clone https://github.com/hamidukarimi/SchoolOS-backend.git
cd SchoolOS-backend
npm install
cp .env.example .env
npm run dev

What's next?

The frontend is currently in development — a React + TypeScript + Tailwind CSS web app that consumes this API. It will be open-source as well.

Building a Production-Grade React Auth Starter (JWT, Refresh Tokens, Zustand, TanStack Query)

Hamid Karimi — Wed, 11 Mar 2026 18:01:14 +0000

Building a Production-Grade React Auth Starter

Authentication is one of those things every frontend developer rebuilds from scratch on every new project. I got tired of that — so I built authforge-client: a clean, scalable React + TypeScript auth starter that handles all the hard parts properly.

GitHub →

What's in the stack

React + TypeScript (Vite + SWC)
TanStack Query — server state and mutations
Zustand — global auth state
Zod — schema validation and TypeScript types
React Hook Form — form management
Framer Motion — animations
Axios — HTTP client with interceptors
Tailwind CSS v4

The architecture

The folder structure is feature-based, not type-based:

src/
├─ api/           # axios instance + endpoints
├─ features/
│  ├─ auth/       # login, register, schemas, hooks, services
│  └─ user/       # change password
├─ components/
│  ├─ ui/         # Button, Input, Alert, Spinner
│  └─ layout/     # Navbar, ProtectedRoute, PublicRoute
├─ store/         # Zustand auth store
├─ context/       # AuthContext (session restore)
├─ hooks/         # useAuth, useLogout
└─ utils/         # token helpers, error handler

Each feature owns its own components, hooks, services, schemas, and types. Adding a new feature never touches existing ones.

The token refresh flow

This is where most auth implementations cut corners. Here's the full flow:

On login/register:

Backend returns accessToken in the response body
Backend sets refreshToken as an httpOnly cookie
Frontend stores accessToken in sessionStorage
User object goes into Zustand

On every API request:

// Axios request interceptor
config.headers.Authorization = `Bearer ${getToken()}`;

On 401 (expired access token):

// Axios response interceptor
if (error.response?.status === 401) {
  // Queue all failed requests
  // Call POST /api/token once
  // Retry all queued requests with new token
}

The failed queue pattern is important — without it, multiple simultaneous 401s would trigger multiple refresh calls, causing race conditions.

On page refresh:

// ProtectedRoute calls restoreSession()
// restoreSession calls POST /api/token
// Gets fresh accessToken + user from refresh token cookie
// Repopulates Zustand

The session restore problem

One subtle bug I ran into: isInitializing starts as false, so on page refresh at /dashboard, the ProtectedRoute would see isAuthenticated: false and immediately redirect to /login — before restoreSession even ran.

The fix was a module-level flag:

let sessionChecked = false;

const ProtectedRoute = () => {
  useEffect(() => {
    if (sessionChecked) return;
    sessionChecked = true;
    void restoreSession();
  }, [restoreSession]);

  // Never redirect until we've actually checked
  if (!sessionChecked || isInitializing) return <Spinner />;

  if (!isAuthenticated) return <Navigate to="/login" />;

  return <Outlet />;
};

Unlike useRef, a module-level variable persists across route changes — so navigating between protected routes doesn't trigger restoreSession again.

Error handling done right

Most tutorials just catch errors and show "Something went wrong." This starter parses errors properly:

// mutationFn catches raw AxiosError and throws ParsedError
mutationFn: async (payload) => {
  try {
    const result = await registerService(payload);
    setToken(result.accessToken);
    setUser(result.user);
  } catch (rawError) {
    throw parseApiError(rawError); // "Email already registered"
  }
}

TanStack Query stores the parsed error, so the UI always shows human-readable messages from the backend.

Multi-step registration form

The register form is split into two steps with Framer Motion slide animations. The key challenge was cross-field validation (password === confirmPassword) on Step 1 before allowing navigation to Step 2.

trigger(["confirmPassword"]) alone doesn't work for cross-field Zod refinements — the fix was using getValues() + setError() manually in the goNext handler:

const goNext = async () => {
  const valid = await trigger([...step1Fields]);
  if (!valid) return;

  const values = getValues();
  if (values.password !== values.confirmPassword) {
    setError("confirmPassword", {
      type: "manual",
      message: "Passwords do not match",
    });
    return;
  }

  setStep(2);
};

What's next

This starter is the auth foundation for Yummy — a full-stack food ordering app I'm building. The backend is an ExpressJS + TypeScript server (also open source) with JWT, MongoDB sessions, role-based access control, and rate limiting.

authforge-express → github.com/hamidukarimi/authforge-express
authforge-client → github.com/hamidukarimi/authforge-client

If this saves you time, drop a ⭐ on GitHub!

I Built an Authentication System With Express.js, MongoDB, (Access/Refresh Tokens, Sessions, Rate Limiting & More)

Hamid Karimi — Sun, 22 Feb 2026 00:24:10 +0000

I recently finished building one of my most solid backend projects — a complete authentication system written in Express.js, powered by MongoDB, JWT, and a clean architecture design.

Here’s what I implemented step-by-step:

**🔐 Access + Refresh tokens with secure storage

🗂️ Session tracking in the database

🧹 Automatic session invalidation

🛡️ IP-based rate limiting (5 attempts / 10 mins)

🧪 Validation middleware for all inputs

⚠️ Global ApiError system for consistent error formatting

🧱 Clean architecture with controllers, services, utils

🛠️ Multiple bug fixes + edge case handling

🚀 Focus on maintainability & production readiness**

This project taught me a LOT about system design, real-world auth, and secure backend development.

If you like it, Hit a ⭐ on GitHub or share it with other developers!

👉 GitHub Repo: https://github.com/hamidukarimi/authforge-express
If you have ideas on improvements or want the front-end version too — let me know!

👋 Hello Dev Community — I’m New Here!

Hamid Karimi — Sat, 06 Dec 2025 18:50:18 +0000

👋 Hello Dev Community — I'm New Here!

Hi everyone! My name is Hamid, and this is my very first post on Dev.to 😊

I'm a full-stack web and mobile app developer skilled in:

React / Next.js
React Native / Expo / Reanimated
Node.js / Express
MongoDB / MySQL
UI/UX Design

I joined Dev.to because I want to:

Share what I learn
Connect with other developers
Improve my skills
Become part of the community

I'm excited to start writing about the things I'm working on — especially React Native animations, mobile apps, and full-stack development.

If you're reading this, feel free to say hi in the comments!

Looking forward to learning from all of you

Thanks for having me here ❤️