DEV Community: Hamid Karimi

Building Vidiflow: A Production-Grade Video Downloader Backend in TypeScript

Hamid Karimi — Sun, 05 Jul 2026 13:18:24 +0000

I Built a Production-Ready Video Downloader Backend in TypeScript — Here's What I Learned

I just completed V2 of Vidiflow, a production-ready backend API for downloading videos from multiple platforms.

This article is the full story of what I built, why I built it this way, and what I learned along the way.

The Challenge

Most video downloader tutorials online are either:

Too simple — basic proof-of-concept projects that don't scale
Too vague — "just use this library" without discussing architecture
Not production-ready — missing authentication, error handling, queues, testing, or documentation

I wanted to build something different.

I wanted to build a backend that could:

Handle thousands of users
Support multiple video platforms
Be easy to extend
Stay maintainable for years

What I Built

Vidiflow Backend is a TypeScript/Node.js API that can:

✅ Accept video URLs from YouTube, TikTok, and more
✅ Extract real metadata (title, formats, quality options)
✅ Return direct download URLs
✅ Track download history
✅ Manage favorite videos
✅ Handle authentication (JWT, refresh tokens, OAuth-ready)
✅ Process downloads asynchronously
✅ Provide real-time download progress via WebSockets
✅ Include complete Swagger/OpenAPI documentation

The Architecture (The Hard Part)

Rather than jumping straight into coding, I designed the architecture first.

That single decision probably saved me more time than anything else during the project.

Feature-Based Modular Structure

src/
└── modules/
    ├── auth/
    ├── downloads/
    ├── users/
    └── providers/

Every feature owns its own code.

For example:

Authentication lives inside auth
Download logic lives inside downloads
Platform implementations live inside providers

A new developer can instantly find where something belongs.

Three-Layer Pattern

Every feature follows the same structure:

Routes
    ↓
Controllers
    ↓
Services
    ↓
Repositories

Routes

Only define HTTP endpoints.

Controllers

Very thin.

They:

validate requests
call services
return responses

Nothing else.

Services

Contain all business logic.

This makes them:

reusable
testable
framework-independent

Repositories

Only communicate with the database.

If I ever switch ORMs or introduce caching, the rest of the application doesn't change.

Key Technical Decisions

1. Provider Architecture

Instead of hardcoding YouTube logic into the download service, I created a provider interface.

interface IProvider {
  name: string;

  canHandle(url: string): boolean;

  getVideoInfo(url: string): Promise<VideoInfo>;

  download(url: string, options): Promise<DownloadResult>;
}

Now every platform becomes its own provider.

Adding a new platform only requires:

one new provider file
one registration line

Nothing else changes.

This makes the system extremely easy to extend.

2. Video Extraction with yt-dlp

Instead of writing extraction logic myself, I integrated yt-dlp.

The backend:

launches yt-dlp as a subprocess
reads its JSON output
converts it into a clean API response

Why?

Because video extraction is incredibly difficult.

Platforms constantly change.

yt-dlp already solves that problem.

My backend simply provides a stable interface around it.

3. Asynchronous Downloads with BullMQ + Redis

Downloads are processed in the background.

Instead of waiting for a long download to finish:

POST /downloads

immediately returns:

downloadId

The worker processes the job separately.

Clients receive updates through WebSockets (or polling if needed).

Benefits:

instant API responses
better scalability
no blocked requests

4. JWT + Refresh Tokens

Authentication follows the standard production pattern.

Access Token

expires in 15 minutes
sent in Authorization header

Refresh Token

valid for 7 days
stored hashed in the database
sent via httpOnly cookie

On logout, refresh tokens are revoked.

This means stolen access tokens only live briefly, while users can still stay logged in securely.

5. Centralized Error Handling

Every service throws typed errors.

Example:

throw new NotFoundError("Video not found");

instead of

throw {
  status: 404,
  message: "Video not found"
};

A single middleware converts every error into a consistent HTTP response.

Controllers stay clean.

No repetitive try/catch blocks.

Designing for Future Growth

One of my goals was making sure V2 could naturally grow into V3.

For example:

Want payments?

→ Add a new billing module.

Need caching?

→ Add Redis inside repositories.

Need mobile apps?

→ Reuse the same API.

Need microservices later?

→ Module boundaries already exist.

Need analytics?

→ Add logging around services.

That's what "designing for scale" means.

Not premature optimization.

Just clean boundaries.

V1 → V2 Journey

V1

Mock data
Placeholder extraction
Architecture prototype

V2

Real yt-dlp integration
WebSocket progress updates
Swagger documentation
Real download URLs
Better error handling
TikTok provider implementation

Even though TikTok extraction is less reliable because of platform restrictions, the provider architecture handled that without affecting the rest of the application.

Project Size

Approximately:

2,500 lines of code

Not huge.

Just intentionally written.

What I Learned

1. Architecture First, Code Second

I spent around two hours designing before writing code.

That probably saved ten hours of refactoring later.

2. Modular > DRY

Not every duplicated function deserves extraction.

But every feature deserves its own home.

Organization matters more than chasing perfect DRY.

3. Typed Errors > Strings

This:

throw new ValidationError(...)

is much better than:

throw {
  status: 400,
  message: "..."
}

TypeScript catches mistakes before runtime.

4. Secrets Belong in `.env`

Hardcoded configuration eventually becomes technical debt.

Even development values belong inside:

.env

.env.example

5. Documentation Isn't Optional

Adding Swagger took less than an hour.

It will save countless hours for anyone using the API.

Documentation is part of the product.

6. Test While You Build

Every endpoint was tested in Postman before moving to the next one.

Small feedback loops catch bugs much earlier.

Tech Stack

Language: TypeScript (Strict Mode)
Runtime: Node.js
Framework: Express.js
Database: PostgreSQL + Prisma ORM
Authentication: JWT + bcrypt
Queues: BullMQ + Redis
Real-Time: Socket.IO
Security: Helmet, CORS, Express Rate Limit, Express Validator
Documentation: Swagger/OpenAPI
Video Extraction: yt-dlp

Everything is container-ready and designed for production deployment.

What's Next?

Backend (V3)

Unit tests
Integration tests
Email verification
Password reset
User profile endpoints
More video providers
Admin monitoring endpoints

Frontend

I'll be building a React frontend that includes:

Authentication
Video downloads
Download history
Favorites
Real-time progress tracking

Future Plans

After that:

Browser extension
Mobile apps
Analytics
Premium features

Open Source

The project is fully open source on GitHub.

It includes:

clean commit history
tagged releases
proper project structure
production architecture

If you're learning backend development, it can serve as a reference for:

Structuring a Node.js application
Designing extensible systems
Implementing authentication
Building async workflows
Writing clean service layers
Handling errors properly

The Biggest Lesson

Building production software isn't about writing more code.

It's about making better decisions.

Things like:

Feature-based organization
Provider architecture
Separation of concerns
Typed errors
Secure authentication
Async processing
Real-time updates
Documentation

None of these ideas are particularly advanced.

They simply require intentional design.

That's what makes a project maintainable.

Advice for Anyone Building Something Similar

If you're building your own backend, I'd recommend:

Start with architecture, not implementation.
Write down why you're choosing a pattern.
Keep responsibilities separated.
Test continuously.
Document the reasoning, not just the API.

That's what separates tutorial projects from production systems.

One More Thing

If you're interested in backend architecture, video downloading, or building scalable TypeScript APIs, feel free to check out the project on GitHub.

It's real code with real trade-offs—not tutorial code.

If you find it useful, I'd really appreciate a ⭐ on the repository.

Feedback, suggestions, and discussions are always welcome.

GitHub Repository:

👉 https://github.com/hamidukarimi/Vidiflow-backend

Final Thought

The biggest win isn't that I built a video downloader.

The biggest win is that I understand every architectural decision inside the codebase.

For me, that's what building real software is all about.

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 ❤️

DEV Community: Hamid Karimi

Building Vidiflow: A Production-Grade Video Downloader Backend in TypeScript

I Built a Production-Ready Video Downloader Backend in TypeScript — Here's What I Learned

The Challenge

What I Built

The Architecture (The Hard Part)

Feature-Based Modular Structure

Three-Layer Pattern

Routes

Controllers

Services

Repositories

Key Technical Decisions

1. Provider Architecture

2. Video Extraction with yt-dlp

3. Asynchronous Downloads with BullMQ + Redis

4. JWT + Refresh Tokens

5. Centralized Error Handling

Designing for Future Growth

V1 → V2 Journey

V1

V2

Project Size

What I Learned

1. Architecture First, Code Second

2. Modular > DRY

3. Typed Errors > Strings

4. Secrets Belong in .env

5. Documentation Isn't Optional

6. Test While You Build

Tech Stack

What's Next?

Backend (V3)

Frontend

Future Plans

Open Source

The Biggest Lesson

Advice for Anyone Building Something Similar

One More Thing

Final Thought

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

What is SchoolOS?

Tech Stack

What's included?

Architecture

Authentication

Response Format

Getting Started

What's next?

Links

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

Building a Production-Grade React Auth Starter

What's in the stack

The architecture

The token refresh flow

The session restore problem

Error handling done right

Multi-step registration form

What's next

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

👋 Hello Dev Community — I’m New Here!

4. Secrets Belong in `.env`