Coder Legion - Recent posts tagged reactjs

Your Next.js redirect() Silently Does Nothing Because It's Inside a try/catch

Fri, 30 Oct 2026 10:08:42 +0000

A user fills in your form and clicks "Create post". The post is saved in the database. And the page shows "Could not create post".

They try again. Now there are two posts.

Nothing is wrong with your database. Your error handling caught something it was never supposed to catch.

The Code That Causes It

// app/actions.ts
'use server';

import { redirect } from 'next/navigation';

export async function createPost(formData: FormData) {
  try {
    const post = await db.post.create({
      data: { title: String(formData.get('title')) },
    });

    redirect(`/posts/${post.id}`);
  } catch (err) {
    return { error: 'Could not create post' };
  }
}

It reads perfectly. Save the post, go to its page, and if anything fails, return an error. A tidy, defensive pattern that you have probably written a hundred times in other frameworks.

Why It Breaks

In Next.js, redirect() does not return. It throws a special error, and the framework catches that error higher up and turns it into a redirect response.

That means your catch block receives it first. Your code swallows the redirect, returns { error: ... }, and the framework never sees it.

The same is true for notFound(), which also works by throwing. Both are written to stop execution immediately, which is why TypeScript treats them as functions that never return.

Why It Is Hard to Catch

The data is saved. The only visible symptom is a wrong error message, so it looks like a UI bug, not a logic bug.
It is inconsistent in your head. The same redirect() works fine outside a try, so you assume it is fine everywhere.
Your logs are confusing. If you log the caught error, you will see a strange error with a NEXT_REDIRECT digest and think something crashed.
It tempts you to retry. Users see an error, submit again and create duplicates.

Fix 1: Keep redirect() Outside the try Block

Only wrap the code that can genuinely fail, and redirect afterwards:

export async function createPost(formData: FormData) {
  let postId: string;

  try {
    const post = await db.post.create({
      data: { title: String(formData.get('title')) },
    });
    postId = post.id;
  } catch (err) {
    return { error: 'Could not create post' };
  }

  redirect(`/posts/${postId}`);
}

The try now covers only the database call. If it fails, you return the error. If it succeeds, execution continues to redirect(), which is outside any catch, so it can do its job.

This is the cleanest option, and it is the one I use by default.

Fix 2: Rethrow If You Must Catch Everything

Sometimes the redirect() sits deep inside a helper, and restructuring is awkward. Then let the framework's own errors pass through your catch. Newer Next.js versions provide a helper for exactly this:

import { redirect, unstable_rethrow } from 'next/navigation';

try {
  // ...work that may call redirect() or notFound() somewhere inside
} catch (err) {
  unstable_rethrow(err); // lets redirect/notFound errors continue upward
  return { error: 'Something went wrong' };
}

The name says it is not final, so check the documentation for the version you use. If it is not available in yours, structure your code as in Fix 1.

Fix 3: Do Not Use Catch-All to Control Flow

A broader habit helps here. A catch (err) with no check is a very wide net. Catch what you expect:

catch (err) {
  if (err instanceof DuplicateTitleError) {
    return { error: 'You already have a post with that title' };
  }
  throw err; // anything else is not yours to handle here
}

Rethrowing what you do not recognize means the framework's own signals, real crashes and bugs all reach the place that is meant to handle them.

Where Else This Bites

notFound() inside try. A missing record becomes your generic error instead of a 404 page.
Route handlers and Server Components. The same rule applies: any try/catch around a call that can redirect or 404 will swallow it.
.catch() on a promise. somePromise.catch(() => null) has the same effect if the promise's code calls redirect().
Wrapper functions. A helper like withErrorHandling(fn) that catches everything will break redirects in every function it wraps.

Quick Checklist

Situation	What to do
`redirect()` after a database write	Put the write in `try`, `redirect()` after it
`notFound()` when a record is missing	Call it outside the `try`, or rethrow
A shared error-handling wrapper	Make it rethrow framework errors
Unsure	Catch specific error types, rethrow the rest

The Rule

redirect() and notFound() signal by throwing, so a catch around them will eat the signal. Keep them outside try blocks, or rethrow what you do not recognize.

Quick audit: search your project for redirect( and notFound(. For each hit, look upward. If it sits inside a try, you have either a bug now or one waiting for the day the code path is used.

If you want a Next.js starting point where forms and actions are set up sensibly from day one, you can browse my templates on pixelanas.com.

Get the templates: https://pixelanas.gumroad.com

Have you ever shipped a form that showed an error after it had succeeded? Tell me in the comments how long it took you to find it.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

How to Build a Custom Admin Panel Without Using WordPress

Thu, 29 Oct 2026 04:26:52 +0000

Every modern web application needs a reliable way to manage its content, users, settings, and business operations. Whether you are building an e-commerce platform, a SaaS application, a customer relationship management system, or a content-driven website, an admin panel makes it possible to control important features without editing the source code every time a change is required.

WordPress provides an administration dashboard that works well for many websites. However, it is not always the right solution for applications that require specialized workflows, complex permissions, custom business logic, or complete control over their architecture.

Building a custom admin panel without WordPress gives developers the freedom to design an interface around the application's actual requirements. Instead of adapting business processes to an existing content management system, you can create a dashboard that fits your data structures, security requirements, and operational needs.

In this article, we will explore how to build a custom admin panel using modern web technologies, including React, Node.js, Express, and PostgreSQL. We will cover architecture, authentication, authorization, CRUD operations, database design, user management, security, testing, and deployment.

By the end, you will understand how to approach a custom admin panel as a maintainable software product rather than simply another dashboard interface.

1. Define the Requirements Before Writing Code

The first step is not choosing a framework. It is understanding what administrators need to accomplish.

An admin panel might allow users to manage products, publish articles, review customer orders, monitor analytics, configure application settings, or manage employee accounts. These requirements determine the structure of the application.

Start by identifying the main modules.

Dashboard: Displays important metrics, recent activities, pending tasks, and operational summaries.

User management: Supports viewing users, updating permitted information, changing account status, and assigning roles.

Content management: Allows administrators to create, edit, publish, archive, and delete content.

Product or inventory management: Provides product listings, stock information, pricing, and category management.

Reports and analytics: Presents trends, transactions, activity summaries, and other business indicators.

Settings: Manages application preferences, notification rules, and other configuration options.

Audit logs: Records important administrative actions so that changes can be investigated later.

Not every application needs every module. A small internal tool may require only user management and reporting, while a larger e-commerce platform may need a complete operational dashboard.

Write user stories before development. For example:

"As an administrator, I want to deactivate a user account so that unauthorized access can be prevented."

"As a content editor, I want to save a draft so that I can publish the article later."

These statements help define functionality, permissions, and acceptance criteria.

2. Choose a Suitable Technology Stack

A custom admin panel can be built with many technologies. The best stack depends on the team's experience, the application's complexity, and its expected growth.

For this example, we will use a JavaScript-based stack.

Frontend: React

React is suitable for building interactive dashboards with reusable components. Tables, forms, navigation menus, charts, modals, and notification messages can all be implemented as independent components.

Useful supporting libraries include:

React Router for navigation.
TanStack Query for server-state management and caching.
React Hook Form for form handling.
Zod for schema validation.
A charting library for visualizing analytics.

A component-based architecture prevents the frontend from becoming a collection of duplicated interface code.

Backend: Node.js and Express

Node.js allows developers to build server-side applications using JavaScript. Express provides a straightforward way to define API endpoints, middleware, authentication checks, and request validation.

The backend should contain business rules and access-control logic. The frontend must never be treated as the final authority on whether a user can perform an administrative action.

Database: PostgreSQL

PostgreSQL is a strong choice for applications that manage structured information such as users, products, orders, and audit records.

Its relational model supports foreign keys, transactions, constraints, and complex queries. These features help maintain data integrity when several administrative operations affect related records.

An ORM such as Prisma can simplify database access, migrations, and schema management.

Styling and interface components

You can use CSS Modules, Tailwind CSS, or a component library to build the interface. The important goal is consistency.

Define reusable styles for spacing, typography, buttons, form controls, alerts, and tables. A consistent design system reduces development time and makes the dashboard easier to maintain.

3. Design the Application Architecture

A maintainable admin panel separates presentation, business logic, and data access.

A typical architecture looks like this:

Administrator's Browser
          |
          v
     React Frontend
          |
          v
     HTTPS REST API
          |
          v
 Express Middleware
          |
          v
 Authentication and Authorization
          |
          v
    Business Services
          |
          v
   Database Access Layer
          |
          v
     PostgreSQL

The frontend handles user interaction and presentation. The API receives requests, validates input, checks permissions, and invokes the appropriate service. The service applies business rules and interacts with the database.

For a small application, a modular monolith is often a practical starting point. It keeps deployment relatively simple while allowing the codebase to be divided into clearly defined modules.

A possible project structure is:

admin-panel/
├── client/
│   └── src/
│       ├── components/
│       ├── layouts/
│       ├── pages/
│       ├── features/
│       ├── hooks/
│       └── services/
├── server/
│   └── src/
│       ├── routes/
│       ├── controllers/
│       ├── middleware/
│       ├── services/
│       ├── validators/
│       └── database/
├── prisma/
│   └── schema.prisma
├── tests/
└── README.md

Each module should have a clear responsibility. Routes define endpoints, controllers coordinate requests and responses, services implement business rules, and the database layer handles persistence.

Avoid placing every operation inside a single large server file. That approach may seem convenient initially, but it becomes difficult to test and extend as the application grows.

4. Design the Database Schema

Database design is one of the most important parts of a custom admin panel. Poorly structured data can create inconsistent records, complicated queries, and difficult migrations.

Consider a simple application that manages administrators, customers, products, and audit events.

A user table might include:

id: A unique identifier.
name: The user's display name.
email: The user's email address.
password_hash: A securely hashed password.
status: The account status.
created_at: The creation timestamp.
updated_at: The latest update timestamp.

Roles and permissions should be modeled separately when the application requires flexible access control.

For example, a user may have an administrator role, while another user has an editor role. The editor might manage content but have no permission to change billing settings.

Products could contain a name, description, price, stock quantity, publication status, and timestamps. Audit records could reference the administrator who performed an action, the action type, the affected resource, and the time it occurred.

Use database constraints to protect data integrity. Email addresses should have appropriate uniqueness constraints, required fields should be non-null where necessary, and relationships should use foreign keys.

Money should be stored using an appropriate decimal or integer representation rather than floating-point arithmetic. Inventory quantities should also have suitable constraints.

Finally, use migrations to manage schema changes. Migrations make database evolution repeatable across development, testing, and production environments.

5. Build Secure Authentication

Authentication determines who is accessing the admin panel. It should be implemented before building sensitive administrative features.

A typical login process works as follows:

The administrator submits an email address and password.
The server validates the request.
The server finds the account and checks its status.
The submitted password is verified against the stored password hash.
The server establishes an authenticated session.
The browser receives an appropriate response and navigates to the dashboard.

Passwords must never be stored in plain text. Use a password-hashing algorithm designed for passwords, such as Argon2id or bcrypt, with appropriate parameters.

For a browser-based administrative application, secure server-managed sessions are often a good choice. Store session identifiers in cookies configured with HttpOnly, Secure, and an appropriate SameSite policy. Use HTTPS in production.

The HttpOnly attribute prevents client-side JavaScript from reading the session cookie. The Secure attribute restricts transmission to HTTPS connections.

Cookie-based authentication also requires careful protection against cross-site request forgery (CSRF). Use appropriate CSRF defenses and validate request origins where suitable.

An alternative is token-based authentication, but tokens require careful handling of expiration, refresh, revocation, and storage. Do not place long-lived sensitive tokens in browser storage without understanding the associated risks.

For higher-risk administrative applications, consider multi-factor authentication, login rate limiting, session expiration, and alerts for suspicious activity.

6. Implement Role-Based Access Control

Logging in should not automatically grant a user every administrative capability.

Role-based access control, commonly called RBAC, assigns permissions according to responsibilities.

For example:

Role	Typical permissions
Super administrator	Manage system configuration and access
Administrator	Manage users and operational resources
Editor	Create and update approved content
Support agent	View customer information and handle support tasks
Analyst	View reports without changing records

The exact permissions should reflect the business requirements.

A simple permission model might contain permissions such as users.read, users.update, products.create, products.delete, and reports.read.

The backend should verify permissions on every protected operation.

function requirePermission(permission) {
  return (req, res, next) => {
    const permissions = req.user?.permissions ?? [];

    if (!permissions.includes(permission)) {
      return res.status(403).json({
        message: "You do not have permission to perform this action."
      });
    }

    next();
  };
}

This middleware is an illustrative example. It assumes that authentication middleware has already populated req.user and that permissions are obtained from a trusted server-side source.

An endpoint could use it like this:

app.get(
  "/api/users",
  requirePermission("users.read"),
  listUsers
);

In a real implementation, ensure the user and their permissions are loaded from a trusted session or validated identity context. Never accept the user's role directly from an untrusted request body.

The frontend can hide buttons that the current user cannot use, but that is only a usability improvement. It is not a security boundary. The API must enforce the same restrictions independently.

Also consider resource-level authorization. Permission to view customer records does not necessarily mean permission to view every customer's sensitive information.

7. Create the Dashboard Layout

The dashboard is the central workspace for administrators. Its design should make important information easy to find without overwhelming the user.

A common layout includes:

A sidebar for primary navigation.
A top navigation bar with account controls and notifications.
A main content area.
Summary cards for important metrics.
Tables for recent activity or pending tasks.
Charts for trends where visualization is useful.

Build the layout as reusable React components.

function AdminLayout({ children }) {
  return (
    <div className="admin-layout">
      <Sidebar />

      <div className="admin-main">
        <Topbar />

        <main className="admin-content">
          {children}
        </main>
      </div>
    </div>
  );
}

The Sidebar and Topbar components can be reused across the application.

Create separate pages for users, products, reports, settings, and other modules. React Router can connect these pages to their respective URLs.

Responsive design is important even when administrators primarily use desktop computers. Users may need to check information from tablets or mobile devices.

On smaller screens, a collapsible sidebar, horizontally scrollable tables, and simplified data cards can make the dashboard usable without compromising essential functionality.

Accessibility should also be part of the layout. Use semantic HTML, visible keyboard focus, descriptive form labels, sufficient contrast, and appropriate error messages.

8. Build CRUD Operations

CRUD stands for Create, Read, Update, and Delete. These four operations form the foundation of many administrative modules.

Consider product management.

An administrator should be able to create a product, view the product list, update its details, and delete or archive it when necessary.

A REST API might expose these endpoints:

GET    /api/products
GET    /api/products/:id
POST   /api/products
PATCH  /api/products/:id
DELETE /api/products/:id

Each endpoint requires authentication, appropriate authorization, request validation, and predictable error handling.

A simplified Express route might look like this:

app.post(
  "/api/products",
  requirePermission("products.create"),
  validateProductInput,
  async (req, res, next) => {
    try {
      const product = await productService.create(req.body);

      res.status(201).json({ data: product });
    } catch (error) {
      next(error);
    }
  }
);

This example assumes that validateProductInput and productService.create are implemented elsewhere. Production code should also ensure that only permitted fields can be submitted and that the database enforces applicable constraints.

For updates, use an allowlist of editable fields rather than blindly passing user-controlled objects to the database. This prevents mass-assignment vulnerabilities, where a request changes fields the user should not control.

Deletion deserves special attention. In many business applications, archiving is safer than permanently deleting a record. Orders, invoices, and financial transactions may need to remain available for audit and reporting purposes.

On the frontend, use forms with clear validation messages and confirmation prompts for destructive operations. Display success or failure notifications so administrators understand whether their action completed.

9. Implement Search, Filtering, and Pagination

Administrative tables often grow quickly. Loading thousands of records into the browser creates unnecessary network traffic and can slow down the interface.

Implement server-side pagination.

For example:

GET /api/products?page=2&limit=25&search=keyboard

The server should validate the page number and limit, apply the search criteria, and return a consistent response.

{
  "data": [],
  "pagination": {
    "page": 2,
    "limit": 25,
    "total": 148,
    "totalPages": 6
  }
}

The example contains an empty data array because it illustrates the response structure rather than actual product records.

Filtering might support product status, category, creation date, or stock availability. Sorting could support name, price, or update time.

Never insert raw user-provided strings directly into SQL queries. Use parameterized queries or safe ORM query methods.

For large datasets, consider indexes on commonly filtered or sorted columns. The correct indexes depend on actual query patterns, so inspect query plans and measure performance before adding many indexes.

Also consider stable sorting. If multiple records share the same timestamp, include a unique identifier as a secondary sort key to avoid inconsistent results between pages.

10. Manage Forms and Validation

Administrative forms frequently handle sensitive or business-critical data. Validation should happen at both the frontend and backend.

Frontend validation improves usability by identifying missing fields or incorrect formats before submission. Backend validation protects the application because requests can be sent without using the frontend at all.

For example, a product form may require:

A non-empty product name.
A valid non-negative price.
A valid inventory quantity.
A recognized product status.
A valid category identifier.

A schema-validation library can express these rules in a reusable format.

import { z } from "zod";

const productSchema = z.object({
  name: z.string().trim().min(1).max(150),
  price: z.number().finite().nonnegative(),
  stock: z.number().int().nonnegative(),
  status: z.enum(["draft", "active", "archived"])
});

This schema illustrates the expected data shape. Your API must also handle JSON parsing, type conversion where appropriate, and validation failures safely.

Do not rely on client-side checks for security. An attacker can bypass them and send requests directly to the API.

For complex workflows, validate business rules as well as individual fields. For example, a product cannot necessarily be archived while it is part of an active fulfillment process.

Good form design also includes clear field labels, sensible defaults, loading states, and protection against accidental duplicate submissions.

11. Add File Uploads Carefully

Many admin panels require image uploads, document attachments, profile pictures, or downloadable reports.

File uploads introduce security and operational concerns beyond ordinary form submissions.

A safe upload workflow should:

Authenticate the user and check upload permissions.
Limit file size and permitted file types.
Validate file content rather than trusting the filename or declared MIME type alone.
Generate a safe server-side filename.
Store files outside executable application directories or in an appropriate object-storage service.
Restrict access to private files.
Scan files for malware when the application's risk profile requires it.

For public product images, object storage with a CDN may be appropriate. For sensitive documents, private storage and short-lived authorized download links are often more suitable.

Do not assume that changing a filename extension makes a file safe. Also avoid exposing uploaded files through unrestricted public URLs when they contain private information.

12. Build Audit Logs and Activity Tracking

Administrative actions can affect customers, financial information, and business operations. Recording important changes helps teams investigate mistakes and detect suspicious behavior.

An audit log might record:

The administrator's identity.
The action performed.
The affected resource.
The timestamp.
The outcome of the operation.
Relevant request or correlation identifiers.

For example, if an administrator changes a customer's account status, the audit record might identify the actor, the affected account, the action, and the time.

Avoid recording passwords, session cookies, authentication tokens, or unnecessary personal information.

Audit logs should be protected against unauthorized modification and deletion. For high-risk systems, consider storing them in a separate access-controlled system or forwarding them to centralized logging infrastructure.

Where appropriate, record before-and-after values for important changes, while carefully excluding sensitive fields.

For critical operations, the business change and its audit event should be written consistently. Database transactions or a transactional outbox pattern can help avoid situations where a change succeeds but its corresponding event is lost.

13. Protect the Application Against Common Attacks

Security should be built into every layer rather than added at the end.

SQL injection

Use parameterized queries and safe database access methods. Never concatenate untrusted input into executable SQL.

Cross-site scripting (XSS)

Render user-generated content safely. Avoid injecting raw HTML unless it has been sanitized with a well-maintained library and there is a clear need.

Cross-site request forgery

For cookie-based authentication, implement suitable CSRF protection for state-changing requests. Use secure cookie settings and validate origins where appropriate.

Broken access control

Check permissions on the server for every protected action. Test direct API requests, not only the visibility of buttons in the interface.

Brute-force attacks

Apply rate limits to login attempts and other sensitive endpoints. Consider multi-factor authentication and monitoring for suspicious patterns.

Session theft

Use HTTPS, secure cookies, sensible session expiration, session rotation where appropriate, and revocation mechanisms for logout and compromised accounts.

Sensitive data exposure

Return only the fields necessary for the requested operation. Avoid sending password hashes, internal secrets, or unnecessary customer information to the browser.

Security misconfiguration

Keep dependencies updated, protect environment variables, configure security headers, disable unnecessary production debugging, and restrict database network access.

Security requirements should be documented and tested. A successful login test alone does not prove that the admin panel is secure.

14. Improve Performance and User Experience

A useful admin panel should feel responsive even when it manages substantial amounts of data.

Start by measuring the application's performance. Identify slow database queries, oversized frontend bundles, repeated API requests, and components that render unnecessarily.

Several techniques can improve responsiveness.

Server-side pagination: Fetch only the records needed for the current view.

Database indexing: Support frequent filtering and sorting operations.

Caching: Cache appropriate read-heavy data, while defining clear invalidation rules for updates.

Lazy loading: Load larger page modules only when users navigate to them.

Debounced search: Avoid sending a new search request for every keystroke.

Optimistic updates: Update the interface immediately for safe operations, then reconcile the result with the server.

Background jobs: Move expensive tasks such as large exports, report generation, or bulk processing out of the main request cycle.

Not every optimization is appropriate for every application. For example, caching frequently changing inventory counts without a clear invalidation strategy can show incorrect information.

Good user experience also requires clear loading, empty, error, and success states. An empty table should explain that no records match the current filters instead of appearing broken.

15. Test the Application Thoroughly

Testing reduces the risk of administrative mistakes and unexpected production failures.

Use several levels of testing.

Unit tests: Verify individual functions, validation rules, and business logic.

Integration tests: Confirm that API endpoints interact correctly with the database and middleware.

End-to-end tests: Simulate workflows such as logging in, creating a product, updating a user, and generating a report.

Authorization tests: Verify that each role can perform permitted actions and receives an appropriate denial for restricted actions.

Security tests: Check input validation, session handling, rate limits, and access-control boundaries.

For example, an authorization test should verify that an editor cannot access an endpoint requiring users.delete, even when the editor manually sends the request.

Also test failure scenarios. What happens when the database is unavailable? What happens when two administrators update the same record? What happens when an upload exceeds the size limit?

These situations matter because admin panels often control operations that cannot simply be ignored when something goes wrong.

Use test databases or isolated test environments. Never run destructive automated tests against production data.

16. Deploy the Admin Panel

A custom admin panel typically requires a frontend hosting environment, an API server, and a database.

A practical deployment workflow includes the following steps:

Configure separate development, staging, and production environments.
Store secrets in environment variables or a secrets manager.
Provision a managed PostgreSQL database or a properly maintained database server.
Configure HTTPS and secure domain routing.
Run automated tests in the deployment pipeline.
Apply reviewed database migrations.
Deploy the frontend and backend.
Verify health checks, logging, and error monitoring.
Confirm that backups are configured and restoration has been tested.

The deployment process should support reliable rollbacks. Database changes require special care because rolling back application code does not automatically reverse every schema change safely.

Use a least-privilege database account for the application. Database administration credentials should not be embedded in frontend code or committed to a public repository.

If the admin panel is intended only for internal staff, consider additional network restrictions or an identity-aware access gateway. Such controls should complement application-level authentication and authorization rather than replace them.

17. Monitor and Maintain the System

Deployment is not the end of development.

Monitor API response times, error rates, database performance, failed login attempts, and background-job failures. Set alerts for conditions that could affect business operations.

Keep dependencies updated and review security advisories. Apply database maintenance and verify backups regularly.

Review administrative permissions as employees change responsibilities. Remove access when accounts are no longer needed and establish a process for responding to compromised accounts.

Collect feedback from actual administrators. If users repeatedly struggle to find a feature, the navigation or information architecture may need improvement.

For a growing application, consider adding configurable dashboards, bulk actions, export tools, notification workflows, and more advanced reporting. Introduce these features according to real operational needs rather than adding complexity without a clear purpose.

18. Common Mistakes to Avoid

Several mistakes can make a custom admin panel difficult to maintain or unsafe to operate.

Building everything in one component: Large components are difficult to test and reuse. Separate layouts, pages, forms, tables, and feature-specific logic.

Trusting the frontend for authorization: Hidden buttons do not protect API endpoints. Every sensitive backend operation must enforce permissions.

Skipping validation: Validate incoming data on the server and enforce important integrity rules in the database.

Ignoring auditability: Important administrative changes should be traceable to an authenticated actor and a specific action.

Loading every record at once: Use server-side pagination and appropriate database queries.

Overengineering the architecture: Microservices, complex permission engines, and distributed caching are not automatically necessary. Start with a well-structured application and evolve when evidence justifies it.

Neglecting accessibility: Administrative tools are productivity software. Keyboard navigation, clear labels, readable tables, and understandable errors improve daily work.

Failing to test recovery procedures: Backups are useful only when they can be restored successfully.

Avoiding these mistakes early can save significant maintenance effort later.

19. A Practical Development Roadmap

If you are building your first custom admin panel, develop it in manageable stages.

Phase 1: Foundation

Define the requirements, choose the stack, create the project structure, design the database, and configure development environments.

Phase 2: Authentication and permissions

Implement secure login, session management, role definitions, permission checks, and account recovery where required.

Phase 3: Core administration

Build the dashboard layout, navigation, user management, and one complete CRUD module.

Phase 4: Data operations

Add search, filtering, pagination, sorting, validation, and carefully designed deletion or archival workflows.

Phase 5: Operational features

Implement audit logs, reports, file uploads, notifications, and background processing according to the application's requirements.

Phase 6: Quality and security

Add automated tests, review access control, inspect dependency risks, test performance, and verify error handling.

Phase 7: Production deployment

Deploy to staging, verify migrations and backups, configure monitoring, and release to production with a rollback plan.

This roadmap keeps the project focused. It also allows developers to deliver useful functionality before investing in optional features.

Conclusion

Building a custom admin panel without WordPress gives developers greater control over application architecture, data management, user permissions, and business workflows. With React, Node.js, Express, and PostgreSQL, it is possible to build an administrative interface that is flexible, maintainable, and capable of supporting complex operations.

However, the quality of an admin panel depends on more than its appearance. Secure authentication, server-side authorization, data validation, reliable database design, audit logging, testing, and operational monitoring are equally important.

The best approach is to begin with clearly defined requirements, build a modular foundation, and add features according to real user needs. A well-designed custom admin panel should simplify administrative work while protecting the data and operations it manages.

WordPress remains a useful option for many content-driven websites, but a custom solution can be a better fit when an application needs specialized functionality or tighter control over its technical architecture.

Ultimately, the goal is not to avoid a particular platform simply for the sake of it. The goal is to build an administrative system that solves the right problems, protects its users, and remains easy to improve as the application grows.

"'use client' Doesn't Turn Your Whole App Into a Client Component (The Children Trick Nobody Explain

Sat, 24 Oct 2026 11:28:48 +0000

You need a theme provider, so you create a file, add 'use client' at the top, and wrap your app in it.

Then a nagging thought arrives: "I just wrapped my entire layout in a client component. Did I turn the whole app into client-side React?"

Most developers either panic and avoid providers, or give up and put 'use client' at the top of every file "just to be safe". Both are the wrong response, and the actual rule is simpler than you expect.

The Setup

// components/ThemeProvider.tsx
'use client';

import { createContext, useState } from 'react';

export const ThemeContext = createContext('light');

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme] = useState('light');
  return <ThemeContext value={theme}>{children}</ThemeContext>;
}

// app/layout.tsx  (a Server Component)
import { ThemeProvider } from '@/components/ThemeProvider';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

ThemeProvider is a Client Component. It wraps every page. So are all the pages client components now?

No.

What 'use client' Actually Does

'use client' marks a boundary. It says: "this file, and everything this file imports, is part of the JavaScript sent to the browser."

The key word is imports. The boundary follows the import graph, not the position in the rendered tree.

In the layout above, children is not imported by ThemeProvider. It is passed in as a prop by the layout, which is a Server Component. The server renders the page first, and hands the finished result to the client component as a slot to fill.

So your pages stay Server Components. They can still fetch data on the server, use secrets, and ship no JavaScript for their static parts.

The Mistake That Does Change Things

Now look at this version:

// components/ThemeProvider.tsx
'use client';

import { Dashboard } from './Dashboard'; // imported, not passed in

export function ThemeProvider() {
  // ...
  return <Dashboard />;
}

Here the client file imports Dashboard, so Dashboard joins the client bundle, along with everything it imports. If it was a Server Component that queried your database, it is no longer one. It will either break the build or quietly ship heavy code to every visitor.

The difference between the two examples is a single word: import versus prop.

The Pattern: Pass Server Components Through as Children

Any time a client component needs to wrap server content, use a slot:

// components/Modal.tsx
'use client';

import { useState } from 'react';

export function Modal({ children }: { children: React.ReactNode }) {
  const [open, setOpen] = useState(false);
  return (
    <>
      <button onClick={() => setOpen(true)}>Show stats</button>
      {open && <div role="dialog">{children}</div>}
    </>
  );
}

// app/page.tsx  (Server Component)
import { Modal } from '@/components/Modal';
import { Stats } from '@/components/Stats'; // reads the database

export default function Page() {
  return (
    <Modal>
      <Stats />
    </Modal>
  );
}

Stats runs on the server, even though it is rendered inside a client component's JSX. The button and the toggle are interactive in the browser. The data never leaves the server except as finished markup.

This works for any prop that holds JSX, not only children. A sidebar prop or a header prop behaves the same way.

Rule of Thumb: Push the Boundary Down

Put 'use client' on the smallest piece that needs interactivity, not on the page:

// Bad: the whole page becomes client code
'use client';
export default function ProductPage() { /* ...200 lines... */ }

// Better: only the button is client code
export default function ProductPage() {
  return (
    <main>
      <ProductDetails />   {/* server */}
      <AddToCartButton />  {/* 'use client' lives here */}
    </main>
  );
}

A page that is mostly text and images, with one button, should send JavaScript for the button, not for the page. Less JavaScript sent means a faster load, which is what I walk through in this plain-language guide to Core Web Vitals.

Two Things That Still Bite

1. Props crossing the boundary must be serializable. Data goes from server to client as text, so you can pass strings, numbers, plain objects, arrays and dates. You cannot pass a regular function. (Server Actions are the exception, because they are designed to cross.)

// Error: functions cannot be passed to Client Components
<ClientButton onClick={() => console.log('hi')} />

Define the handler inside the client component instead.

2. A server-only module can leak into the client by import. If a client file imports a helper that touches your database or secrets, the build either fails or bundles code you never meant to ship. The server-only package turns that into a loud build error:

// lib/db.ts
import 'server-only';

Import this file from a client component and the build fails, instead of shipping the connection code.

The Rule

'use client' marks an import boundary, not a rendering zone. Whatever a client file imports goes to the browser. Whatever you pass to it as props or children can stay on the server. Keep the directive on small interactive leaves, and use the children slot for everything else.

Quick audit: search your project for 'use client' and look at each file. If it is a page or a layout, ask whether it really needs state or browser APIs. If it is a wrapper, check that it receives its content as children and does not import it.

If you want a Next.js starting point built around the App Router, you can browse my templates on pixelanas.com.

Get the templates: https://pixelanas.gumroad.com

Where in your project is 'use client' doing more than it needs to? Drop it in the comments, and tell me if the children trick surprised you.

Anas, full-stack Next.js developer building SaaS products and premium templates. X: @ASheikh69751

Building a File Upload System with React and Python

Wed, 21 Oct 2026 06:50:08 +0000

File uploads are an essential feature of modern web applications. Whether users are uploading profile pictures, submitting documents, sharing reports, attaching files to messages, or managing media in a SaaS platform, a reliable file upload system plays an important role in the overall user experience.

Although uploading a file might seem like a simple task, building a production-ready system requires careful planning. Developers must consider frontend usability, backend validation, security, storage management, error handling, performance, and scalability.

React provides an interactive frontend for selecting files, displaying upload progress, and communicating with backend APIs. Python, particularly with FastAPI, provides an efficient way to receive files, validate their contents, enforce upload limits, and store them securely.

In this article, we will explore how to build a complete file upload system using React and Python. We will examine the architecture, implementation details, security considerations, and strategies for preparing the system for production.

1. Understanding the File Upload Architecture

A file upload system typically consists of three major components:

Frontend: React handles file selection, previews, validation feedback, and upload progress.
Backend: Python receives the uploaded file, performs validation, checks authorization, and manages the upload process.
Storage: Files are saved in local storage, a private object storage service, or another appropriate storage solution.

The communication between these components generally follows an HTTP request-response pattern.

When a user selects a file, React creates a FormData object and sends it to the backend using an HTTP POST request. The backend validates the request and stores the file. After successful processing, the API returns a response containing information about the uploaded file.

A typical workflow looks like this:

The user selects a file.
React performs basic client-side validation.
The frontend sends the file using multipart form data.
FastAPI checks authentication, authorization, file size, and permitted file types.
The backend generates a safe storage name.
The file is stored in the configured storage system.
The API returns a success response.
React updates the interface with the upload result.

This separation of responsibilities makes the application easier to maintain and extend.

2. Setting Up the Python Backend

For this implementation, we will use FastAPI because it provides straightforward request handling, automatic API documentation, and support for asynchronous web applications.

First, create a project directory:

mkdir file-upload-system
cd file-upload-system

python -m venv venv

Activate the virtual environment.

On Windows:

venv\Scripts\activate

On Linux or macOS:

source venv/bin/activate

Install the required dependencies:

pip install fastapi uvicorn python-multipart

The packages serve different purposes:

fastapi provides the backend framework.
uvicorn runs the application.
python-multipart enables multipart form-data parsing.

Create the following project structure:

file-upload-system/
├── backend/
│   ├── main.py
│   └── uploads/
└── frontend/
    └── src/
        ├── App.jsx
        └── App.css

The uploads directory will be used for local development. In a production deployment, private files should generally be stored outside publicly served application directories or in private object storage.

3. Building the File Upload API with FastAPI

The first step is to create an API endpoint that receives and stores uploaded files.

Create backend/main.py:

from pathlib import Path
from uuid import uuid4
import os

from fastapi import (
    FastAPI,
    File,
    HTTPException,
    UploadFile,
)
from fastapi.middleware.cors import CORSMiddleware

app = FastAPI(title="File Upload API")

BASE_DIR = Path(__file__).resolve().parent
UPLOAD_DIR = BASE_DIR / "uploads"
UPLOAD_DIR.mkdir(parents=True, exist_ok=True)

MAX_FILE_SIZE = 5 * 1024 * 1024

ALLOWED_EXTENSIONS = {
    ".pdf",
    ".png",
    ".jpg",
    ".jpeg",
}

app.add_middleware(
    CORSMiddleware,
    allow_origins=[
        "http://localhost:5173"
    ],
    allow_credentials=True,
    allow_methods=["GET", "POST"],
    allow_headers=["*"],
)


@app.post("/api/upload")
async def upload_file(
    file: UploadFile = File(...)
):
    original_name = Path(
        file.filename or ""
    ).name

    extension = Path(
        original_name
    ).suffix.lower()

    if not original_name:
        raise HTTPException(
            status_code=400,
            detail="A filename is required."
        )

    if extension not in ALLOWED_EXTENSIONS:
        raise HTTPException(
            status_code=400,
            detail="File type is not allowed."
        )

    file_id = uuid4().hex
    stored_name = f"{file_id}{extension}"
    destination = UPLOAD_DIR / stored_name

    total_size = 0

    try:
        with destination.open("xb") as output:
            while True:
                chunk = await file.read(1024 * 1024)

                if not chunk:
                    break

                total_size += len(chunk)

                if total_size > MAX_FILE_SIZE:
                    raise HTTPException(
                        status_code=413,
                        detail="File exceeds the 5 MB limit."
                    )

                output.write(chunk)

        return {
            "message": "File uploaded successfully.",
            "file_id": file_id,
            "filename": original_name,
            "size": total_size,
            "content_type": file.content_type,
        }

    except HTTPException:
        destination.unlink(missing_ok=True)
        raise

    except OSError:
        destination.unlink(missing_ok=True)
        raise HTTPException(
            status_code=500,
            detail="Could not save the uploaded file."
        )

    finally:
        await file.close()

This endpoint provides a basic foundation for handling uploads.

How the backend works

File reception: FastAPI uses UploadFile to receive the uploaded file. Unlike reading the entire file into a Python byte string, UploadFile uses a spooled temporary file, which is more suitable for many upload scenarios.

Extension validation: The code restricts uploads to PDF, PNG, JPG, and JPEG extensions. This helps enforce the application's expected file types, but it does not prove that the file actually contains valid content of that type.

Unique storage names: A UUID generates a unique storage identifier. This prevents users from overwriting files simply by uploading files with identical names.

Size enforcement: The endpoint reads the file in chunks and stops when the configured size limit is exceeded.

Cleanup: If writing fails or the file exceeds the limit, the partially written destination is removed.

This example is suitable for learning and local development. A public production API needs additional safeguards, including authentication, authorization, content inspection, and limits at the reverse proxy or application server.

4. Creating the React Frontend

Now that the backend is available, we can build a React interface that allows users to select and upload files.

A Vite-based React project can be created with the following commands:

npm create vite@latest frontend -- --template react
cd frontend
npm install

Start the development server:

npm run dev

Create or replace src/App.jsx with the following implementation:

import { useState } from "react";
import "./App.css";

const MAX_FILE_SIZE = 5 * 1024 * 1024;

const ALLOWED_TYPES = [
  "application/pdf",
  "image/png",
  "image/jpeg",
];

export default function App() {
  const [file, setFile] = useState(null);
  const [status, setStatus] = useState("");
  const [error, setError] = useState("");
  const [uploading, setUploading] = useState(false);
  const [result, setResult] = useState(null);

  function handleFileChange(event) {
    const selectedFile = event.target.files?.[0];

    setError("");
    setStatus("");
    setResult(null);

    if (!selectedFile) {
      setFile(null);
      return;
    }

    if (selectedFile.size > MAX_FILE_SIZE) {
      setError("Please select a file smaller than 5 MB.");
      setFile(null);
      return;
    }

    if (!ALLOWED_TYPES.includes(selectedFile.type)) {
      setError("Only PDF, PNG, and JPEG files are allowed.");
      setFile(null);
      return;
    }

    setFile(selectedFile);
  }

  async function handleUpload() {
    if (!file || uploading) return;

    setUploading(true);
    setError("");
    setStatus("");
    setResult(null);

    const formData = new FormData();
    formData.append("file", file);

    try {
      const response = await fetch(
        "http://localhost:8000/api/upload",
        {
          method: "POST",
          body: formData,
        }
      );

      const data = await response.json();

      if (!response.ok) {
        throw new Error(
          data.detail || "Upload failed."
        );
      }

      setResult(data);
      setStatus("File uploaded successfully!");
      setFile(null);
    } catch (err) {
      setError(
        err.message || "Unable to upload the file."
      );
    } finally {
      setUploading(false);
    }
  }

  return (
    <main className="upload-page">
      <section className="upload-card">
        <h1>File Upload System</h1>

        <p>
          Select a PDF, PNG, or JPEG file
          up to 5 MB.
        </p>

        <label htmlFor="file-input">
          Choose a file
        </label>

        <input
          id="file-input"
          type="file"
          accept=".pdf,.png,.jpg,.jpeg"
          onChange={handleFileChange}
        />

        {file && (
          <div className="file-info">
            <strong>{file.name}</strong>
            <span>
              {(file.size / 1024).toFixed(2)} KB
            </span>
          </div>
        )}

        <button
          type="button"
          onClick={handleUpload}
          disabled={!file || uploading}
        >
          {uploading ? "Uploading..." : "Upload File"}
        </button>

        {status && (
          <p className="success">{status}</p>
        )}

        {error && (
          <p className="error" role="alert">
            {error}
          </p>
        )}

        {result && (
          <div className="result">
            <h2>Upload Details</h2>
            <p>File: {result.filename}</p>
            <p>File ID: {result.file_id}</p>
            <p>Size: {result.size} bytes</p>
          </div>
        )}
      </section>
    </main>
  );
}

Important implementation details

The frontend uses React state to keep track of the selected file, upload status, errors, and successful results.

The FormData API prepares the request body in the format expected by FastAPI's UploadFile parameter.

Notice that the code does not manually set the Content-Type header. The browser automatically generates the correct multipart boundary when sending a FormData object. Setting this header manually can cause request parsing problems.

The interface also disables the upload button while a request is in progress. This helps prevent accidental duplicate submissions.

Client-side validation improves usability, but it must never replace server-side validation. Anyone can bypass browser restrictions and send requests directly to the API.

5. Styling the Upload Interface

A clean interface helps users understand what they are uploading and whether the operation succeeded.

Create src/App.css:

* {
  box-sizing: border-box;
}

body {
  margin: 0;
  font-family: Arial, sans-serif;
  background: #f3f5f9;
  color: #1f2937;
}

.upload-page {
  min-height: 100vh;
  display: flex;
  justify-content: center;
  align-items: center;
  padding: 24px;
}

.upload-card {
  width: 100%;
  max-width: 520px;
  padding: 32px;
  border-radius: 16px;
  background: white;
  box-shadow: 0 10px 35px rgba(0, 0, 0, 0.08);
}

.upload-card h1 {
  margin-top: 0;
  font-size: 28px;
}

.upload-card p {
  line-height: 1.6;
  color: #596579;
}

.upload-card input {
  display: block;
  width: 100%;
  margin: 16px 0;
}

.upload-card button {
  width: 100%;
  padding: 13px 18px;
  border: none;
  border-radius: 8px;
  background: #2563eb;
  color: white;
  font-size: 16px;
  cursor: pointer;
}

.upload-card button:disabled {
  opacity: 0.55;
  cursor: not-allowed;
}

.file-info,
.result {
  margin: 18px 0;
  padding: 14px;
  border: 1px solid #e5e7eb;
  border-radius: 8px;
  overflow-wrap: anywhere;
}

.file-info {
  display: flex;
  flex-direction: column;
  gap: 8px;
}

.success {
  color: #15803d !important;
}

.error {
  color: #b91c1c !important;
}

This responsive layout works well as a starting point for a small application. A more advanced interface could include drag-and-drop uploads, file previews, progress indicators, cancellation controls, and a history of uploaded files.

6. Running the Complete Application

Open two terminal windows.

In the first terminal, start the backend:

cd file-upload-system/backend

uvicorn main:app --reload --port 8000

In the second terminal, start the React frontend:

cd file-upload-system/frontend

npm run dev

Open the frontend URL displayed by Vite, usually:

http://localhost:5173

Select a supported file and click the upload button.

If the upload succeeds, the frontend displays the original filename, generated file identifier, and file size. The stored file should appear in the backend's uploads directory.

FastAPI also provides interactive API documentation at:

http://localhost:8000/docs

The documentation is useful for testing the upload endpoint independently of React.

7. Understanding File Upload Security

File uploads introduce security risks because users can submit arbitrary content to an application. A secure system must treat uploaded files as untrusted input.

Validate file size

Large uploads can consume memory, disk space, bandwidth, and processing capacity. Establish clear upload limits and enforce them on the server.

For larger files, use streaming or multipart upload techniques rather than loading entire files into memory.

The example reads the file in chunks, but FastAPI and its underlying multipart parser may already have processed or spooled request data before the endpoint begins reading it. Therefore, production deployments should also configure request-body limits at the proxy or gateway and test oversized requests.

Validate actual file content

File extensions and browser-supplied MIME types are not trustworthy on their own. A malicious user can rename an executable or another unexpected file with a .jpg extension.

Depending on the supported file types, stronger validation can include:

Checking file signatures or magic bytes.
Parsing documents with appropriate libraries.
Fully decoding uploaded images.
Rejecting malformed or unexpected content.
Running malware scanning where appropriate.

Do not assume that a valid signature guarantees a safe file. File parsers can contain vulnerabilities, and malicious files may have valid headers.

Generate server-controlled filenames

Never rely on a user-provided filename as the storage path.

A filename can contain unexpected characters, path separators, or misleading extensions. Generating a UUID or another server-controlled identifier reduces path traversal and collision risks.

Keep the original filename separately as metadata if the application needs to display it to the user.

Restrict access to uploaded files

Uploaded documents should not automatically become public.

For private documents, verify that the authenticated user is authorized to access the requested file. Store ownership information in a database and enforce permissions on every download request.

Avoid exposing internal storage paths or allowing users to guess file identifiers and retrieve other users' content.

Configure CORS correctly

Cross-Origin Resource Sharing determines which browser origins may access an API. In production, configure an explicit list of trusted origins.

CORS is not authentication and does not prevent direct requests from scripts or other clients. Backend authentication and authorization are still required.

8. Adding Authentication and Authorization

A production file upload service should usually require an authenticated user.

For example, a FastAPI dependency can verify a bearer token before allowing an upload:

from fastapi import Depends, HTTPException
from fastapi.security import HTTPBearer

security = HTTPBearer()

async def get_current_user(
    credentials = Depends(security)
):
    token = credentials.credentials

    user = verify_access_token(token)

    if user is None:
        raise HTTPException(
            status_code=401,
            detail="Invalid or expired token."
        )

    return user

Here, verify_access_token represents application-specific token verification and must be implemented using a trusted authentication library and appropriate token-validation rules.

The dependency can then be added to an endpoint:

@app.post("/api/secure-upload")
async def secure_upload(
    file: UploadFile = File(...),
    current_user = Depends(get_current_user),
):
    # Validate and store the file.
    # Associate it with current_user.id.
    ...

In a real application, the endpoint must also enforce quotas, validate content, and associate the stored file with the correct account.

Authentication establishes who the user is. Authorization determines what that user is allowed to do. For example, an employee might be allowed to upload documents to their own workspace but not to another organization's workspace.

These rules must be enforced by the backend, not merely by hiding buttons in React.

9. Choosing the Right Storage Strategy

The storage solution should match the application's requirements.

Local filesystem storage

Local storage is convenient for development, prototypes, and certain single-server deployments.

Advantages include straightforward implementation, low initial complexity, and direct access to files.

However, local storage becomes difficult to manage when multiple application instances need access to the same files. Containers and ephemeral hosting environments may also lose stored data when instances are replaced.

Object storage

Object storage is usually a better option for scalable applications. Services such as Amazon S3, Google Cloud Storage, and Azure Blob Storage provide durable storage designed for large collections of files.

Advantages include:

Independent scaling of application servers and file storage.
Lifecycle policies for archiving and deleting files.
Integration with access controls and encryption.
Support for direct or multipart uploads.
Easier distribution of approved public content through a CDN.

For private files, keep buckets private and provide authorized downloads through short-lived signed URLs or a backend download endpoint.

Database metadata

Large binary files are often stored outside a relational database, while file metadata is stored in PostgreSQL or another database.

A metadata record might contain:

id
owner_id
original_filename
storage_key
content_type
file_size
checksum
status
created_at

This structure allows the application to search files, track ownership, manage retention, and enforce permissions without storing every file's bytes directly in a database table.

10. Uploading Directly to Object Storage

As an application grows, sending every file through the Python backend can increase server bandwidth usage and operational costs.

A common alternative is a presigned-upload workflow.

The process generally works as follows:

React requests permission to upload a file.
The backend authenticates the user and checks upload permissions.
The backend creates a short-lived presigned URL for an approved object key.
React uploads the file directly to object storage.
The application verifies that the object was uploaded successfully.
The backend records the final metadata and marks the upload as complete.

This approach reduces the amount of file data passing through the application server.

However, the backend must not blindly trust a client-side completion notification. It should verify the object, its size, and relevant metadata using the storage provider's API.

Presigned URLs should be short-lived and scoped to a specific operation and object. They should not grant broader access than necessary.

11. Implementing Upload Progress

Users benefit from seeing how much of a file has been uploaded, particularly when working with larger documents.

The basic fetch API does not offer a widely supported browser interface for tracking upload-body progress in the same way that XMLHttpRequest does.

One option is to use Axios:

npm install axios

An upload function could look like this:

import axios from "axios";

async function uploadFile(file, token, onProgress) {
  const formData = new FormData();

  formData.append("file", file);

  const response = await axios.post(
    "http://localhost:8000/api/upload",
    formData,
    {
      headers: {
        Authorization: `Bearer ${token}`,
      },
      onUploadProgress(event) {
        if (event.total) {
          const percentage = Math.round(
            (event.loaded / event.total) * 100
          );

          onProgress(percentage);
        }
      },
    }
  );

  return response.data;
}

This example assumes the application already has a valid access token and that the API requires bearer authentication. The token should come from the application's established authentication flow.

React can store the reported percentage in state and render a progress bar.

Keep in mind that upload progress measures the request body being transmitted. It does not necessarily mean that server-side validation, malware scanning, or storage processing has finished.

A complete user experience should distinguish between uploading, processing, completed, and failed states.

12. Handling Errors and Network Failures

Network requests can fail for many reasons, including interrupted connections, server errors, invalid files, expired authentication, and storage failures.

A robust upload interface should display clear and actionable messages.

Examples include:

400 Bad Request: The uploaded file violates an application rule.
401 Unauthorized: The user must authenticate or renew their session.
403 Forbidden: The user does not have permission to perform the operation.
413 Content Too Large: The request exceeds an upload limit.
429 Too Many Requests: The user has exceeded a rate limit.
500 Internal Server Error: An unexpected backend failure occurred.

Do not display raw stack traces or sensitive infrastructure details to users. Log technical details on the server and return a safe error message to the frontend.

For retry support, use an explicit retry button or a carefully designed automatic retry policy. Avoid blindly retrying every failed POST request because the original upload may have succeeded even if the response was lost.

For critical workflows, use upload identifiers, idempotency mechanisms, or a status-check endpoint to avoid creating duplicate files.

13. Supporting Multiple File Uploads

Some applications allow users to upload several documents at once.

React can support this by enabling the multiple attribute:

<input
  type="file"
  multiple
  accept=".pdf,.png,.jpg,.jpeg"
  onChange={(event) => {
    const selectedFiles = Array.from(
      event.target.files || []
    );

    console.log(selectedFiles);
  }}
/>

The backend can accept a list of files using FastAPI's list[UploadFile] type.

When implementing multi-file uploads, define limits for the number of files, individual file sizes, and total request size.

It is also useful to track the status of each file independently. If one upload fails, the interface should indicate which file failed and allow the user to retry that file without unnecessarily uploading everything again.

For large batches, limit concurrency rather than starting hundreds of simultaneous uploads. This reduces pressure on the browser, network, backend, and storage service.

14. Database Integration with PostgreSQL

A database becomes valuable when users need a file library, search functionality, ownership tracking, or administrative controls.

A PostgreSQL table could be created as follows:

CREATE TABLE uploaded_files (
    id UUID PRIMARY KEY,
    owner_id UUID NOT NULL,
    original_filename TEXT NOT NULL,
    storage_key TEXT NOT NULL UNIQUE,
    content_type TEXT,
    file_size BIGINT NOT NULL,
    status TEXT NOT NULL DEFAULT 'pending',
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

The owner_id should reference the application's user table in a complete schema. The database should also enforce appropriate constraints for valid statuses, file sizes, and other business rules.

A typical upload workflow creates a pending record, stores the file, and updates the record after successful storage and validation.

In a production application, failures must be handled carefully. For example, if the file is stored successfully but the database update fails, the application may need a cleanup job to identify orphaned objects.

Similarly, if a database record is created but storage fails, the system should mark the upload as failed or remove the incomplete record according to its retention policy.

Because database transactions do not automatically include external object storage, reliable systems often use explicit upload states and background reconciliation jobs.

15. Background Processing and File Scanning

Not every upload can be processed immediately.

An application might need to generate image thumbnails, extract PDF text, inspect document contents, or scan files for malware.

Performing these operations inside the main HTTP request can increase response times and reduce API throughput.

A more scalable design places uploaded files into a processing workflow:

Receive and validate the initial request.
Store the file in a private location.
Record the upload as pending.
Submit a background job.
Process or scan the file.
Update the status to approved, rejected, or failed.
Notify the frontend when the result becomes available.

Python tools such as Celery or other task queue systems can help manage background processing.

The worker should operate with limited permissions and should not execute uploaded files. Files that fail security checks should remain inaccessible to normal users and be handled according to a documented quarantine and deletion policy.

16. Testing the File Upload System

Testing helps prevent regressions and reveals security weaknesses before deployment.

Backend tests

Use a test client to verify that the API accepts valid files and rejects invalid requests.

Test cases should include:

A valid PDF within the configured size limit.
An unsupported file extension.
An empty file.
A file that exceeds the size limit.
A malformed image or document.
A missing file field.
An unauthenticated request.
An authenticated user attempting to access another user's file.

Also test cleanup behavior when writing or validation fails.

Frontend tests

React tests should verify that the interface displays validation messages, disables the upload button during submission, handles failed responses, and shows the success result.

Test network interruptions and expired authentication as well as ordinary success scenarios.

Integration tests

Integration tests confirm that the frontend and backend agree on request field names, response structures, allowed file types, and error formats.

A file upload system may work correctly in isolation while failing in production because of CORS configuration, reverse-proxy limits, storage permissions, or deployment differences.

17. Performance and Scalability Best Practices

A reliable upload system should be designed around expected file sizes, traffic patterns, and operational requirements.

Stream data where appropriate. Avoid unnecessarily loading large files entirely into application memory. Chunked reading and direct-to-object-storage uploads can reduce resource pressure.

Use upload limits at multiple layers. Application checks should be combined with gateway or reverse-proxy limits to protect the service from oversized requests.

Apply rate limiting and quotas. Prevent a single user or automated client from consuming excessive bandwidth or storage.

Keep storage independent. For distributed deployments, use shared durable storage rather than depending on a single application instance's local filesystem.

Use background workers. Move expensive scanning, conversion, and extraction tasks out of the main request-response path.

Monitor resource consumption. Track upload success rates, file sizes, processing latency, storage costs, and failed jobs.

Plan for cleanup. Define retention periods for temporary uploads, abandoned multipart sessions, rejected files, and orphaned objects.

These practices help maintain predictable performance as usage grows.

18. Deploying the Application to Production

Before deploying the system, review the entire upload lifecycle.

Configure environment-specific settings rather than hardcoding storage credentials, secret keys, or production URLs in the source code.

Use HTTPS to protect data in transit. Keep private files outside publicly accessible directories and ensure that download endpoints enforce authorization.

Configure reverse-proxy body-size limits consistently with the application's intended upload policy. Verify that the hosting platform, application server, and storage service all support the expected file sizes.

Add structured logging and monitoring while avoiding the logging of authentication tokens, sensitive file contents, or unnecessary personal information.

A production deployment should also include dependency updates, backups or appropriate storage durability controls, database migrations, and a recovery plan for failed processing jobs.

Finally, test the application under realistic conditions. A successful upload on a developer's machine does not prove that the system will work correctly with multiple concurrent users or interrupted network connections.

Conclusion

Building a file upload system with React and Python involves much more than selecting a file and sending an HTTP request. A dependable implementation needs a well-designed API, clear frontend feedback, strict server-side validation, secure storage, appropriate access controls, and reliable error handling.

React makes it possible to create an intuitive interface for selecting files, reporting progress, and displaying upload results. FastAPI provides a practical foundation for receiving and validating files, while PostgreSQL and object storage can support ownership, metadata management, and long-term scalability.

For a small application, a local-storage implementation can be a useful starting point. As the application grows, private object storage, presigned uploads, background processing, database-backed metadata, and stronger security controls can provide a more scalable architecture.

The most important principle is to treat every uploaded file as untrusted input. Validate it on the backend, enforce permissions consistently, limit resource consumption, and design for failure from the beginning.

With these practices in place, developers can build file upload systems that are maintainable, secure, and ready to evolve alongside modern web applications.

How to Build a Multi User Dashboard with Role-Based Access

Tue, 20 Oct 2026 06:04:12 +0000

Modern web applications often serve multiple types of users, including administrators, managers, employees, customers, and external partners. Although these users may work within the same application, they do not necessarily need access to the same features, information, or operations.

For example, an administrator might need to manage users, review reports, and configure application settings. A manager may need to monitor team performance and assign tasks, while an employee may only need to view assigned projects and update their progress. Giving every user the same level of access creates unnecessary security risks and makes the application more difficult to manage.

This is where a multi-user dashboard with Role-Based Access Control (RBAC) becomes valuable.

RBAC is a security approach that assigns permissions to roles rather than granting individual permissions to every user separately. When a user signs in, the application determines their role and allows them to access the appropriate features and resources.

In this article, we will explore how to build a secure, scalable multi-user dashboard using React, FastAPI, PostgreSQL, and JSON Web Tokens (JWT). We will examine the architecture, database schema, authentication workflow, frontend implementation, backend authorization, testing strategies, and deployment considerations.

By the end, you will understand how to create a dashboard that supports multiple user roles while maintaining a clear separation between authentication, authorization, and business logic.

1. Understanding Multi-User Dashboards

A multi-user dashboard is a centralized interface where different users can interact with an application according to their responsibilities and access rights.

Unlike a basic dashboard that displays identical information to everyone, a role-aware dashboard adapts its navigation, available actions, and data visibility to the authenticated user.

Consider a project management platform with three roles:

Administrator

Create, update, and deactivate user accounts.
Assign roles and permissions.
Access organization-wide reports.
Configure application settings.

Manager

View team performance.
Create and assign tasks.
Review employee progress.
Access reports related to their team.

Employee

View assigned tasks.
Update task status.
Edit permitted profile information.
Access personal performance metrics.

Each role has a different set of responsibilities. The dashboard should reflect those differences without requiring separate applications for every user type.

A well-designed multi-user dashboard offers several benefits:

Improved security: Users receive only the permissions necessary for their responsibilities.
Better user experience: Unnecessary menus and actions remain hidden.
Simplified administration: Permissions can be managed centrally.
Scalability: New roles and features can be introduced without redesigning the entire application.
Maintainability: Access rules remain separate from presentation components and business logic.

However, hiding a button is not sufficient security. The backend must independently validate every protected operation.

2. Choosing the Technology Stack

Before writing code, it is important to choose technologies that support maintainability, security, and future growth.

For this project, we will use the following stack.

React

React provides a component-based approach to building interactive interfaces. Components such as navigation menus, data tables, statistics cards, and protected pages can be reused across different parts of the dashboard.

React is particularly useful when different roles require different interfaces but share common layout components.

FastAPI

FastAPI is a Python framework for building APIs. It supports request validation, dependency injection, asynchronous programming, and automatic API documentation.

We can use FastAPI dependencies to verify authenticated users and enforce role-based permissions before executing protected endpoints.

PostgreSQL

PostgreSQL stores users, roles, permissions, and application data. Its relational structure makes it suitable for applications where users belong to teams or organizations and access depends on several related records.

SQLAlchemy

SQLAlchemy provides an object-relational mapping layer that allows Python code to interact with PostgreSQL using models and database queries.

JWT and password hashing

JWT access tokens can be used to authenticate API requests. Passwords should be stored using a dedicated password-hashing algorithm such as Argon2id or bcrypt, never as plain text.

Additional tools

A production application may also use:

React Router for client-side navigation.
Pydantic for data validation.
Alembic for database migrations.
Pytest for backend tests.
Vitest and React Testing Library for frontend tests.
Docker for consistent deployment environments.

The specific libraries can change, but the underlying principles of authentication, authorization, and least-privilege access remain the same.

3. Designing the Application Architecture

A reliable dashboard separates the user interface, API, database, and authorization logic.

The basic request flow looks like this:

A user opens the React application.
The user submits their login credentials.
FastAPI verifies the credentials.
The server issues an appropriate authentication token or session.
React requests the current user's profile and permitted dashboard data.
FastAPI authenticates each request and checks the required permissions.
PostgreSQL returns only the data the user is authorized to access.
React renders the permitted information and available actions.

This separation is important because the frontend should never be the ultimate authority for access decisions.

For example, an employee might modify a JavaScript variable to pretend to be an administrator. If the backend trusts the role supplied by the browser, the employee could access restricted functionality.

Instead, the backend must derive the authenticated identity from a verified session or token and enforce permissions independently.

A practical project structure could look like this:

multi-user-dashboard/
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   │   ├── Sidebar.jsx
│   │   │   ├── Header.jsx
│   │   │   └── ProtectedRoute.jsx
│   │   ├── pages/
│   │   │   ├── Login.jsx
│   │   │   ├── Dashboard.jsx
│   │   │   ├── Users.jsx
│   │   │   └── Reports.jsx
│   │   ├── services/
│   │   │   └── api.js
│   │   ├── auth/
│   │   │   └── AuthContext.jsx
│   │   └── App.jsx
│   └── package.json
├── backend/
│   ├── app/
│   │   ├── main.py
│   │   ├── models.py
│   │   ├── schemas.py
│   │   ├── database.py
│   │   ├── security.py
│   │   ├── permissions.py
│   │   └── routes/
│   │       ├── auth.py
│   │       ├── users.py
│   │       └── reports.py
│   └── requirements.txt
├── tests/
└── docker-compose.yml

This organization keeps related responsibilities together and prevents the main application file from becoming difficult to maintain.

4. Designing the Database Schema

Database design is one of the most important parts of a role-based dashboard.

A simple application can begin with a users table containing a role column. However, a growing application benefits from separate tables for users, roles, and permissions.

A flexible design uses four main tables:

Users: Stores account information.

Roles: Defines roles such as administrator, manager, and employee.

Permissions: Defines individual actions, such as users.read, users.manage, and reports.read.

Role permissions: Connects roles to their permitted actions.

The relationships can be represented as follows:

Users
  |
  | role_id
  v
Roles
  |
  | role_id
  v
RolePermissions
  |
  | permission_id
  v
Permissions

A simplified SQL schema might look like this:

CREATE TABLE roles (
    id SERIAL PRIMARY KEY,
    name VARCHAR(50) UNIQUE NOT NULL
);

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    email VARCHAR(255) UNIQUE NOT NULL,
    password_hash TEXT NOT NULL,
    role_id INTEGER NOT NULL REFERENCES roles(id),
    is_active BOOLEAN NOT NULL DEFAULT TRUE,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

CREATE TABLE permissions (
    id SERIAL PRIMARY KEY,
    code VARCHAR(100) UNIQUE NOT NULL,
    description TEXT
);

CREATE TABLE role_permissions (
    role_id INTEGER NOT NULL REFERENCES roles(id)
        ON DELETE CASCADE,
    permission_id INTEGER NOT NULL REFERENCES permissions(id)
        ON DELETE CASCADE,
    PRIMARY KEY (role_id, permission_id)
);

In a real application, database migrations should create and modify these tables instead of relying on ad hoc manual changes.

The schema can be extended with organizations, teams, projects, and audit logs when the business requirements demand them.

It is also important to distinguish role-based permissions from data ownership. A manager may have permission to read reports but should not automatically be able to read reports belonging to every organization.

5. Implementing Authentication with FastAPI

Authentication answers the question: Who is making this request?

Authorization answers a different question: What is this user allowed to do?

These concepts should remain separate.

First, install the necessary backend packages:

pip install fastapi uvicorn sqlalchemy \
    psycopg[binary] pyjwt pwdlib[argon2]

The precise package versions should be pinned and reviewed for compatibility in the project's dependency file.

Hashing passwords

Passwords must never be stored in plain text. Password hashing transforms a password into a one-way representation that can be verified later.

A simplified example using pwdlib is:

from pwdlib import PasswordHash

password_hasher = PasswordHash.recommended()

def hash_password(password: str) -> str:
    return password_hasher.hash(password)

def verify_password(
    password: str,
    password_hash: str
) -> bool:
    return password_hasher.verify(
        password,
        password_hash
    )

When registering a user, save the resulting hash rather than the original password.

When logging in, retrieve the account by email and verify the submitted password against the stored hash.

The registration process should also validate email addresses, enforce suitable password policies, and avoid exposing sensitive details in error messages.

Creating an authentication endpoint

The login endpoint should validate credentials, check that the account is active, and establish an authenticated session.

A simplified endpoint structure is:

from fastapi import APIRouter, HTTPException, status

router = APIRouter(prefix="/auth", tags=["Authentication"])

@router.post("/login")
def login(credentials: LoginRequest):
    user = find_user_by_email(credentials.email)

    if (
        user is None
        or not verify_password(
            credentials.password,
            user.password_hash
        )
        or not user.is_active
    ):
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Invalid credentials"
        )

    return create_authenticated_session(user)

The functions and request schema shown here represent application-specific helpers that must be implemented using the database and security configuration.

For JWT-based authentication, the server signs tokens using a securely managed key and a suitable signing algorithm. Tokens should include an expiration time and an appropriate subject identifier.

The application must validate the signature, expiration, issuer, audience, and other relevant claims.

For browser applications, an alternative is a server-managed session in a cookie configured with HttpOnly, Secure, and an appropriate SameSite policy. Cookie-based authentication also requires appropriate CSRF protections.

Neither approach should expose long-lived credentials to unnecessary JavaScript access.

6. Building the Authorization Layer

Authorization is where role-based access control becomes effective.

Instead of writing separate role checks in every API endpoint, create reusable dependencies that verify a user's permissions.

Consider a FastAPI dependency:

from fastapi import Depends, HTTPException, status

def require_permission(permission_code: str):
    def permission_checker(
        current_user = Depends(get_current_user)
    ):
        if not user_has_permission(
            current_user,
            permission_code
        ):
            raise HTTPException(
                status_code=status.HTTP_403_FORBIDDEN,
                detail="Insufficient permissions"
            )

        return current_user

    return permission_checker

Here, get_current_user must validate the incoming session or token, while user_has_permission must resolve the user's current effective permissions.

A protected endpoint can then declare its access requirement:

@router.get("/users")
def list_users(
    current_user = Depends(
        require_permission("users.read")
    )
):
    return get_authorized_users(current_user)

The example assumes that the database query and data-scope restrictions are implemented correctly.

The key advantage is consistency. Every endpoint using the dependency follows the same authorization policy.

An administrator can be granted users.read and users.manage, while a manager might receive users.read only for team members. An employee may have neither permission.

For a small application, a role-based check can be sufficient:

def require_role(*allowed_roles: str):
    def role_checker(
        current_user = Depends(get_current_user)
    ):
        if current_user.role.name not in allowed_roles:
            raise HTTPException(
                status_code=403,
                detail="Access denied"
            )

        return current_user

    return role_checker

However, permission-based checks generally offer greater flexibility as the number of features and roles increases.

A critical rule is that the backend must never trust a role name submitted by the frontend. It should derive authorization from a verified identity and trusted server-side data.

7. Implementing Role-Based Permissions

A permission model should describe actions rather than merely naming users.

For example:

Permission	Administrator	Manager	Employee
View own dashboard	Yes	Yes	Yes
Manage all users	Yes	No	No
View team reports	Yes	Yes	No
View organization reports	Yes	No	No
Update assigned tasks	Yes	Yes	Yes
Change application settings	Yes	No	No

These are example policies, not universal rules. A real project should define permissions according to its business requirements.

A permission can follow a naming convention such as:

users.read
users.create
users.update
users.delete
tasks.read
tasks.update
reports.read
settings.manage

This structure makes the policy easier to understand and extend.

Instead of scattering conditions throughout the codebase, maintain a central authorization layer and test the policy systematically.

Avoiding permission escalation

Only authorized administrators should be able to assign privileged roles.

For example, an employee update endpoint should not accept unrestricted changes to fields such as role_id, is_active, or is_superuser.

Use separate request schemas for ordinary profile updates and administrative account management.

Always validate the target user's permissions and the acting user's authority before changing roles.

Role changes should also be logged so that unexpected privilege escalation can be investigated.

8. Building the React Authentication Context

The React frontend needs to know whether the user is authenticated and which interface to display.

An authentication context can share this information between components without passing user details through every component manually.

A simplified example is:

import {
  createContext,
  useContext,
  useEffect,
  useState
} from "react";

const AuthContext = createContext(null);

export function AuthProvider({ children }) {
  const [user, setUser] = useState(null);
  const [loading, setLoading] = useState(true);

  useEffect(() => {
    async function loadCurrentUser() {
      try {
        const response = await fetch("/api/auth/me", {
          credentials: "include"
        });

        if (response.ok) {
          setUser(await response.json());
        }
      } finally {
        setLoading(false);
      }
    }

    loadCurrentUser();
  }, []);

  return (
    <AuthContext.Provider
      value={{ user, setUser, loading }}
    >
      {children}
    </AuthContext.Provider>
  );
}

export function useAuth() {
  return useContext(AuthContext);
}

This example assumes that the application uses an authenticated cookie and that /api/auth/me returns the current user's safe profile.

The endpoint must not return password hashes, signing secrets, or other sensitive fields.

In a complete implementation, network errors should be handled explicitly, session expiry should be addressed, and login and logout operations should update the context consistently.

The loading state is important because React should not briefly display protected content before the authentication check finishes.

9. Protecting React Routes

React Router can prevent users from navigating to pages that should not be visible to them.

A route guard might look like this:

import { Navigate, Outlet } from "react-router-dom";
import { useAuth } from "./AuthContext";

export default function ProtectedRoute({
  allowedRoles
}) {
  const { user, loading } = useAuth();

  if (loading) {
    return <p>Loading dashboard...</p>;
  }

  if (!user) {
    return <Navigate to="/login" replace />;
  }

  if (
    allowedRoles &&
    !allowedRoles.includes(user.role)
  ) {
    return <Navigate to="/forbidden" replace />;
  }

  return <Outlet />;
}

The route configuration can group pages by role:

<Route element={
  <ProtectedRoute
    allowedRoles={["admin"]}
  />
}>
  <Route
    path="/admin/users"
    element={<UserManagement />}
  />
</Route>

The exact role representation must match the profile returned by the backend.

Route protection improves the user experience, but it is not a substitute for server-side authorization. Anyone can bypass frontend navigation by calling an API directly.

Therefore, every protected API endpoint must enforce the relevant permissions even when its corresponding React route is already protected.

A useful dashboard should display only the navigation options that are relevant to the current user.

Define the navigation items in one configuration:

const navigationItems = [
  {
    label: "Dashboard",
    path: "/dashboard",
    roles: ["admin", "manager", "employee"]
  },
  {
    label: "User Management",
    path: "/admin/users",
    roles: ["admin"]
  },
  {
    label: "Team Reports",
    path: "/reports/team",
    roles: ["admin", "manager"]
  },
  {
    label: "My Tasks",
    path: "/tasks",
    roles: ["admin", "manager", "employee"]
  }
];

The sidebar can filter the list according to the authenticated user's role:

function Sidebar({ role }) {
  const visibleItems = navigationItems.filter(
    item => item.roles.includes(role)
  );

  return (
    <nav>
      {visibleItems.map(item => (
        <a key={item.path} href={item.path}>
          {item.label}
        </a>
      ))}
    </nav>
  );
}

In a real application, use React Router's Link or NavLink components instead of ordinary anchors for internal navigation.

For permission-based navigation, filter items against a permission set rather than hard-coding role names. This approach supports custom roles without requiring every navigation component to understand the entire authorization model.

The same principle applies to action buttons. For example, a user without users.create should not see an option to create accounts.

Nevertheless, the backend must reject unauthorized creation requests even if a user manually constructs one.

11. Creating Different Dashboard Views

After authentication and authorization are in place, the next step is designing the dashboard itself.

A reusable layout should contain common elements such as the header, sidebar, content area, notification panel, and profile menu.

Inside that layout, each user role can have a different dashboard view.

Administrator dashboard

Administrators may need a high-level overview of the organization.

Useful components include:

Total registered users.
Active and inactive accounts.
Recent administrative activities.
User management shortcuts.
System health indicators.
Organization-wide performance reports.

Sensitive administrative metrics should be retrieved through endpoints that enforce the required permissions.

Manager dashboard

Managers generally need team-level information.

Their dashboard could include:

Number of assigned employees.
Tasks in progress.
Overdue tasks.
Team completion rates.
Pending approvals.
Team performance trends.

The backend should limit these metrics to teams the manager is authorized to oversee.

Employee dashboard

Employees benefit from a simpler interface focused on their daily responsibilities.

Possible components include:

Assigned tasks.
Upcoming deadlines.
Recent notifications.
Personal performance metrics.
Profile information.
Quick links to common actions.

Avoid loading every dashboard widget from one enormous endpoint. Separate API resources make permission enforcement clearer and allow each page to load the data it actually needs.

12. Enforcing Data-Level Access Control

One of the most common RBAC mistakes is checking whether a user can access a feature without checking which records the user may access.

For example, a manager might be permitted to read task details but should not automatically be able to access every employee's tasks.

Imagine a request to retrieve a task:

@router.get("/tasks/{task_id}")
def get_task(
    task_id: int,
    current_user = Depends(get_current_user)
):
    task = get_task_from_database(task_id)

    if task is None:
        raise HTTPException(
            status_code=404,
            detail="Task not found"
        )

    if not can_view_task(current_user, task):
        raise HTTPException(
            status_code=403,
            detail="Access denied"
        )

    return task

The helper can_view_task must implement the application's actual ownership, team, and organizational rules.

For greater reliability, enforce data scopes directly in database queries whenever practical.

For example, an employee's task query should include the employee's authenticated user ID. A manager's query should include only the IDs of teams that manager is permitted to access.

This reduces the risk of insecure direct object references, where changing a record identifier exposes another user's data.

A robust access policy often combines RBAC with ownership checks or attribute-based access control (ABAC).

RBAC answers which actions a role can perform. Ownership and attributes determine whether that action is permitted on a particular record.

13. Building Dashboard APIs Efficiently

The frontend should retrieve data through clearly defined endpoints.

A possible API design is:

POST   /api/auth/login
POST   /api/auth/logout
GET    /api/auth/me

GET    /api/dashboard/summary

GET    /api/users
POST   /api/users
PATCH  /api/users/{user_id}

GET    /api/tasks
POST   /api/tasks
PATCH  /api/tasks/{task_id}

GET    /api/reports/team
GET    /api/reports/organization

Every endpoint should have an explicit authentication requirement and authorization policy.

For example, GET /api/reports/organization may require an organization-wide reporting permission, while GET /api/reports/team may allow managers to access only their assigned teams.

Avoid relying on the endpoint's name or location to provide security. The policy must be implemented in the actual request handler or its dependencies.

Pagination and filtering

Dashboard tables can become slow when they retrieve thousands of records in a single request.

Use pagination and server-side filtering.

For example:

GET /api/tasks?page=1&page_size=25&status=pending

The backend should validate pagination parameters, apply the authenticated user's data scope, and then execute the query.

Filtering and sorting must be implemented safely. User-provided column names should not be inserted directly into raw SQL statements.

Caching considerations

Caching can improve dashboard performance, but it can also expose data if cache entries are shared across users with different permissions.

Cache keys should reflect the relevant user, organization, and authorization scope. Sensitive responses should not be placed in shared caches without a clear security model.

When permissions change, the system should also consider how cached authorization decisions and dashboard data are invalidated.

14. Handling Authentication and Session Security

Security must be part of the design from the beginning.

A role-based dashboard may contain employee information, customer records, financial reports, or administrative operations. Poor session management can undermine even a carefully designed permission model.

Important practices include the following.

Use short-lived access credentials

Access tokens should have reasonable expiration times. If refresh tokens are used, implement rotation, revocation, and appropriate reuse detection.

Protect browser storage

Avoid storing long-lived authentication tokens in browser storage where injected JavaScript could read them.

HttpOnly cookies can reduce token theft through JavaScript, although they require proper CSRF defenses and careful cookie configuration.

Configure CORS correctly

Cross-Origin Resource Sharing should allow only the origins required by the application.

Avoid permissive wildcard configurations, especially when credentials are involved.

Validate every request

Validate request bodies, query parameters, identifiers, and update fields. Do not assume the frontend has already performed validation.

Prevent brute-force attacks

Apply appropriate rate limits to login and other sensitive endpoints. Monitor repeated failed login attempts and consider additional protections for high-risk accounts.

Protect privileged accounts

Require stronger authentication controls for administrative users where practical, including multifactor authentication.

Use HTTPS

All production authentication traffic should use HTTPS. Secure cookies and appropriate transport security configurations help protect credentials in transit.

Avoid leaking sensitive information

Do not include secrets, password hashes, or internal authorization details in API responses or application logs.

Security depends on the complete request lifecycle, not a single authentication library.

15. Managing Role Changes and Permission Updates

User roles often change as employees move between teams or receive new responsibilities.

A manager might become an administrator, or an employee might lose access after leaving a project.

These changes should take effect according to a clearly defined policy.

If authorization depends on permissions stored in the database, the backend can resolve current permissions on each request or use a carefully designed cache with invalidation.

If roles and permissions are embedded in JWT claims, those claims may become outdated before the token expires.

For that reason, highly privileged operations should not rely exclusively on long-lived role claims without considering revocation and role-change behavior.

Possible solutions include:

Short-lived access tokens.
Server-side sessions.
Token versioning.
Session revocation.
Rechecking current permissions for sensitive operations.

The appropriate approach depends on the application's scale and risk profile.

Role assignment should also be auditable. Record who changed a role, which account was affected, when the change occurred, and whether the operation succeeded.

16. Testing the Authorization Model

A dashboard can look correct while containing serious access-control vulnerabilities. Testing should therefore cover both successful operations and forbidden requests.

Start by creating test accounts for each role.

Then build a permission matrix that identifies which actions should succeed or fail for each account.

Example tests include:

Administrator tests

Can access user management.
Can create authorized user accounts.
Can access permitted organization-wide reports.
Cannot bypass validation or access data outside their organization.

Manager tests

Can view permitted team reports.
Can update tasks within their authorized scope.
Cannot assign themselves administrative privileges.
Cannot retrieve unrelated teams' private records.

Employee tests

Can view their own dashboard.
Can update assigned tasks where allowed.
Cannot access administrator endpoints.
Cannot modify another user's profile or task by changing an identifier.

Testing with Pytest

A backend test might look like this:

def test_employee_cannot_list_users(
    employee_client
):
    response = employee_client.get("/api/users")

    assert response.status_code == 403

The test assumes that the employee lacks the permission required by the endpoint and that employee_client represents a correctly authenticated test client.

Additional tests should cover expired tokens, inactive accounts, revoked sessions, invalid permissions, missing credentials, and unexpected database failures.

For resource-level access, create records belonging to different users and verify that changing the record identifier never grants unauthorized access.

Frontend tests should also confirm that restricted navigation items and actions are hidden or disabled appropriately.

However, frontend tests cannot establish backend security on their own. The API must be tested directly.

17. Improving Dashboard Performance

Performance becomes important when a dashboard displays multiple data tables, charts, notifications, and activity feeds.

A few architectural decisions can make a significant difference.

Optimize database queries

Use appropriate indexes for commonly filtered fields, including foreign keys and frequently queried status columns.

Inspect query plans before adding indexes indiscriminately.

Avoid unnecessary requests

Fetch data when the relevant page needs it. Use request caching and invalidation through an appropriate data-fetching library when the application becomes more complex.

Split large components

Separate dashboard cards, tables, filters, and chart components into manageable units.

This makes the interface easier to test and reduces unnecessary rendering.

Use lazy loading

Load large reports or less frequently visited pages only when users open them.

Paginate large datasets

Return manageable pages of records instead of sending the entire dataset to the browser.

Monitor real-world behavior

Track API latency, error rates, database query performance, and frontend loading times.

Performance optimization should be driven by actual measurements rather than assumptions.

18. Improving the User Experience

A secure dashboard should also be easy to understand.

Users should be able to determine what they can do without navigating through irrelevant features.

Consider these improvements:

Clear navigation: Organize features according to the user's responsibilities.

Useful empty states: Explain what a user can do when there are no tasks, reports, or notifications.

Accessible design: Provide keyboard navigation, clear focus indicators, semantic HTML, and suitable color contrast.

Responsive layouts: Ensure tables, menus, and dashboard cards work on desktop, tablet, and mobile screens.

Meaningful feedback: Display clear success and error messages after important operations.

Confirmation for destructive actions: Require appropriate confirmation before deleting records or performing other irreversible operations.

Consistent loading states: Show skeletons, spinners, or loading indicators while data is being retrieved.

Permission-aware error handling: Explain when a user lacks access without exposing internal security details.

Avoid treating role-based design as an excuse to create completely separate user interfaces. Reuse common components wherever possible and customize only the sections that genuinely differ.

19. Logging and Auditing Administrative Actions

A production dashboard should provide visibility into important security events.

Useful audit events include:

Successful and failed authentication attempts.
Role and permission changes.
User account creation and deactivation.
Sensitive report access where justified.
Changes to important business records.
Rejected privileged operations.

An audit record might contain:

event_id
actor_user_id
action
resource_type
resource_id
timestamp
request_id
outcome

Additional fields can be introduced where necessary, but logs should not contain passwords, access tokens, or unnecessary personal information.

Audit logs should be protected against unauthorized modification and access. For important compliance requirements, consider exporting them to a dedicated monitoring or logging platform.

Logging is not a replacement for access control. Its purpose is to support monitoring, investigation, and accountability.

20. Deploying the Application

Once the dashboard passes testing, prepare it for production.

The React frontend can be built as static assets and hosted on an appropriate web server or frontend hosting platform. FastAPI can run behind a production-ready application server and reverse proxy. PostgreSQL should run in a managed database service or a properly secured database environment.

Docker can help make development and deployment environments more consistent.

A production deployment checklist should include:

Configure environment variables and secret management.
Use a dedicated database account with limited privileges.
Apply database migrations.
Enable HTTPS.
Configure allowed frontend origins.
Set appropriate cookie and session policies.
Configure database backups and recovery procedures.
Add health checks and application monitoring.
Apply rate limits to sensitive endpoints.
Verify role and resource-level authorization.
Test account deactivation and session revocation.
Review dependency updates and security advisories.

Never commit production secrets, signing keys, or database passwords to a public repository.

Also, avoid running database migrations automatically in every application worker at startup. A controlled deployment step is easier to reason about and reduces migration race conditions.

After deployment, monitor errors and latency, test backup restoration periodically, and establish a process for responding to security incidents.

21. Common Mistakes to Avoid

Several mistakes repeatedly appear in role-based dashboard implementations.

Trusting frontend roles

A role stored in React state can be changed by a user. The backend must verify permissions independently.

Giving every administrator unlimited access

Administrative privileges should be carefully defined and restricted to legitimate needs. Separate high-risk permissions when appropriate.

Ignoring record ownership

Permission to access a feature does not necessarily mean permission to access every record within that feature.

Using one oversized API endpoint

Returning all application data from a single endpoint complicates authorization, increases response size, and can reveal information unnecessarily.

Hard-coding role checks everywhere

Repeated conditional logic becomes difficult to maintain. Centralize authorization rules and test them systematically.

Forgetting permission revocation

Role changes, account deactivation, and session revocation must have defined effects on existing sessions and tokens.

Skipping negative tests

It is not enough to prove that administrators can access restricted resources. Tests must also prove that unauthorized users cannot.

Returning sensitive fields

Use response schemas that expose only the data a particular endpoint is intended to return.

Avoiding these mistakes early is generally easier than correcting them after a security incident.

22. A Practical Development Roadmap

For developers building their first multi-user dashboard, an incremental implementation plan is often the most effective approach.

Phase 1: Requirements and design

Identify user roles, permissions, data ownership rules, and core dashboard features. Document the permission matrix before writing authorization code.

Phase 2: Database and authentication

Create the user and role models, implement password hashing, establish login and logout flows, and define how sessions will be validated.

Phase 3: Backend authorization

Implement reusable permission dependencies and apply them to every protected endpoint. Add data-scope checks for teams, organizations, and owned records.

Phase 4: React application

Build the authentication context, protected routes, reusable dashboard layout, and role-aware navigation.

Phase 5: Dashboard functionality

Implement the statistics cards, data tables, filters, reports, task management, and user management features required by the application.

Phase 6: Testing

Test each role against both permitted and forbidden actions. Include direct API requests, cross-user record access, expired sessions, and role changes.

Phase 7: Production readiness

Configure HTTPS, secure cookies or tokens, monitoring, audit logs, database backups, and deployment automation.

Phase 8: Iteration

Review user feedback and performance metrics. Introduce new permissions or roles only when there is a clear business need.

This roadmap keeps the implementation manageable while ensuring that security is considered throughout development.

Conclusion

Building a multi-user dashboard with role-based access requires more than creating a few conditional React components. It involves designing a clear authorization model, securing authentication, protecting API endpoints, limiting access to individual records, and testing the complete system against unauthorized requests.

React provides a flexible interface for presenting role-specific dashboards. FastAPI offers a practical foundation for reusable authentication and authorization dependencies, while PostgreSQL provides reliable storage for users, roles, permissions, and application data.

By combining least-privilege permissions, resource-level authorization, secure session management, comprehensive testing, and structured deployment practices, developers can build dashboards that are maintainable today and ready to grow with future business requirements.

A well-designed role-based dashboard is not simply an interface that changes depending on who logs in. It is a secure application architecture that ensures every user can perform the right actions, access the right information, and do so without compromising the privacy or integrity of other users' data.

Building a Real Time Notification System with React and WebSockets

Tue, 20 Oct 2026 03:24:57 +0000

Modern web applications need to communicate with users instantly. Whether someone receives a new message, a payment confirmation, an order update, a project assignment, or a security alert, they expect the information to appear without refreshing the page. Real-time notifications have become an essential feature of dashboards, social media platforms, e-commerce applications, collaboration tools, and customer management systems.

Traditional web applications often rely on polling to check whether new information is available. Although polling is straightforward to implement, it can generate unnecessary HTTP requests and introduce delays. WebSockets provide a more efficient communication model by establishing a persistent, bidirectional connection between the browser and the server.

When combined with React, WebSockets make it possible to build responsive notification interfaces that update automatically as events occur.

In this article, we will explore how to design, implement, secure, test, and scale a real-time notification system using React, JavaScript, Node.js, and WebSockets. We will also discuss notification persistence, unread counters, reconnection strategies, database integration, and production deployment.

1. Understanding Real-Time Notifications

A real-time notification is a message delivered to a user when a particular event happens. Unlike traditional alerts that require the user to refresh a page or revisit a section, real-time notifications can appear immediately while the application remains open.

Consider a project management application. When a team member assigns a task to another employee, the backend records the assignment and sends a notification to the appropriate user. If that user is currently online, the notification appears in the React interface almost immediately.

Common notification events include:

New messages in a conversation.
Changes to an order or delivery status.
Payment confirmations and billing alerts.
New comments, mentions, or reactions.
Task assignments and project updates.
System maintenance and security warnings.

A reliable notification system should do more than display a temporary message. It should identify the recipient, preserve important events, maintain unread counts, support marking notifications as read, and recover gracefully when a connection is interrupted.

The goal is to deliver a consistent experience whether users are actively interacting with the application or returning after being offline.

2. What Are WebSockets?

WebSockets are a communication protocol that enables two-way communication between a client and a server over a persistent connection. After the initial connection is established, both sides can send messages independently without creating a new HTTP request for every update.

According to the MDN WebSockets documentation, this communication model allows applications to exchange data without repeatedly polling the server.

Reference: https://developer.mozilla.org/en-US/docs/Web/API/WebSocket

In a traditional polling approach, the browser might request notification updates every five seconds. If thousands of users keep polling, the backend must process a large number of requests even when no new notifications exist.

With WebSockets, the browser establishes a connection and waits. When an event occurs, the server sends the notification through that connection.

WebSockets versus polling

Polling is easy to understand and works with almost any HTTP backend. However, it can waste resources when updates are infrequent and may introduce delays between polling intervals.

Long polling keeps an HTTP request open until the server has an update or a timeout occurs. It can reduce unnecessary requests but introduces additional request-management complexity.

WebSockets maintain a persistent connection and support bidirectional messaging. They are particularly useful when updates must be delivered quickly or when the client also needs to send real-time events.

Server-Sent Events (SSE) are another option when the browser primarily needs one-way updates from the server. The right choice depends on the application's communication requirements.

For a notification system that needs low-latency delivery and may later support features such as live chat or collaborative updates, WebSockets are a strong option.

3. Designing the System Architecture

Before writing code, it is important to understand the responsibilities of each component.

A practical architecture contains five major parts:

React frontend: Displays notifications, unread counts, connection status, and user interactions.
WebSocket server: Maintains active connections and delivers events to authenticated users.
Application backend: Generates notifications when business events occur.
Database: Stores notification records so users can access them after reconnecting.
Message broker: Coordinates event delivery across multiple backend instances when the application scales.

The basic event flow looks like this:

A user performs an action, such as creating an order. The backend validates the action and stores the resulting business data. It then creates a notification event for the intended recipient. The WebSocket layer sends the event to the user's active connection, and React updates the interface.

If the recipient is offline, the notification remains in persistent storage and can be retrieved through an HTTP API when the user returns.

This distinction is essential: WebSockets provide a delivery channel, but they should not be the only place where important notification data exists.

4. Choosing the Technology Stack

For this implementation, we will use a JavaScript-based stack.

React: Builds the notification interface.
Node.js: Runs the server-side JavaScript environment.
Express: Provides HTTP routes for the backend.
ws: Provides a WebSocket server implementation for Node.js.
PostgreSQL or another database: Stores notifications and read states.
Redis or a message broker: Supports cross-instance event distribution when required.

The ws library is a useful choice for demonstrating the underlying WebSocket protocol directly. Socket.IO is another popular option that adds features such as automatic reconnection and fallback transports. However, Socket.IO and native WebSockets are different protocols and are not interchangeable without compatible client and server implementations.

We will use the ws library for the server and the browser's native WebSocket API for the React client.

5. Creating the Backend WebSocket Server

First, create a project directory and install the required dependencies.

mkdir realtime-notifications
cd realtime-notifications
npm init -y
npm install express ws cors

Create a file named server.js.

The following example demonstrates a basic WebSocket server that associates connections with users and sends notifications to the correct recipient. It uses a simplified demonstration authentication mechanism; production applications must replace it with real authentication and authorization.

const express = require("express");
const http = require("http");
const WebSocket = require("ws");
const cors = require("cors");

const app = express();

app.use(cors({
  origin: "http://localhost:5173",
}));

app.use(express.json());

const server = http.createServer(app);

const wss = new WebSocket.Server({
  server,
  path: "/ws",
});

const clients = new Map();

wss.on("connection", (socket, request) => {
  // Demonstration only: do not trust a user ID
  // supplied directly by a client in production.
  const url = new URL(
    request.url,
    "http://localhost:3000"
  );

  const userId = url.searchParams.get("userId");

  if (!userId) {
    socket.close(1008, "Authentication required");
    return;
  }

  if (!clients.has(userId)) {
    clients.set(userId, new Set());
  }

  clients.get(userId).add(socket);

  socket.on("close", () => {
    const connections = clients.get(userId);

    if (!connections) return;

    connections.delete(socket);

    if (connections.size === 0) {
      clients.delete(userId);
    }
  });

  socket.on("error", (error) => {
    console.error("WebSocket error:", error);
  });
});

function sendNotification(userId, notification) {
  const connections = clients.get(String(userId));

  if (!connections) return;

  const message = JSON.stringify({
    type: "notification",
    payload: notification,
  });

  for (const socket of connections) {
    if (socket.readyState === WebSocket.OPEN) {
      socket.send(message);
    }
  }
}

app.post("/api/notifications/demo", (req, res) => {
  const { userId, title, message } = req.body;

  if (!userId || !title || !message) {
    return res.status(400).json({
      error: "userId, title, and message are required",
    });
  }

  const notification = {
    id: crypto.randomUUID(),
    title,
    message,
    createdAt: new Date().toISOString(),
    read: false,
  };

  sendNotification(userId, notification);

  res.status(202).json({
    success: true,
    notification,
  });
});

server.listen(3000, () => {
  console.log("Server running on port 3000");
});

Add the following import near the top of the file if your Node.js environment does not expose crypto globally:

const crypto = require("node:crypto");

The example uses an in-memory Map to track active connections. Each user maps to a set of WebSocket connections, allowing the same account to connect from multiple browser tabs or devices.

When a connection closes, the server removes it from the set and deletes the user entry if no active connections remain.

There are two important limitations. First, this example does not persist notifications. Second, the userId query parameter is not secure authentication. Anyone who can connect and choose an arbitrary user ID could impersonate another recipient.

We will address both issues in the production design sections below.

6. Building the React Notification Component

Next, create a React application. If you are using Vite, the following commands will get you started.

npm create vite@latest client -- --template react
cd client
npm install
npm run dev

Create a component called NotificationCenter.jsx.

This component will establish a WebSocket connection, listen for incoming messages, update the notification list, and calculate the unread count.

import { useEffect, useState } from "react";

export default function NotificationCenter({ userId }) {
  const [notifications, setNotifications] = useState([]);
  const [connectionStatus, setConnectionStatus] =
    useState("connecting");

  useEffect(() => {
    if (!userId) return;

    const socket = new WebSocket(
      `ws://localhost:3000/ws?userId=${encodeURIComponent(userId)}`
    );

    socket.addEventListener("open", () => {
      setConnectionStatus("connected");
    });

    socket.addEventListener("message", (event) => {
      try {
        const data = JSON.parse(event.data);

        if (data.type !== "notification") return;

        setNotifications((previous) => [
          data.payload,
          ...previous,
        ]);
      } catch (error) {
        console.error("Invalid WebSocket message:", error);
      }
    });

    socket.addEventListener("error", () => {
      setConnectionStatus("error");
    });

    socket.addEventListener("close", () => {
      setConnectionStatus("disconnected");
    });

    return () => {
      socket.close();
    };
  }, [userId]);

  const unreadCount = notifications.filter(
    (notification) => !notification.read
  ).length;

  function markAsRead(id) {
    setNotifications((previous) =>
      previous.map((notification) =>
        notification.id === id
          ? { ...notification, read: true }
          : notification
      )
    );
  }

  return (
    <section className="notification-center">
      <header>
        <h2>Notifications</h2>
        <span>Unread: {unreadCount}</span>
      </header>

      <p>Connection: {connectionStatus}</p>

      {notifications.length === 0 ? (
        <p>No notifications yet.</p>
      ) : (
        <ul>
          {notifications.map((notification) => (
            <li key={notification.id}>
              <strong>{notification.title}</strong>
              <p>{notification.message}</p>

              {!notification.read && (
                <button
                  onClick={() => markAsRead(notification.id)}
                >
                  Mark as read
                </button>
              )}
            </li>
          ))}
        </ul>
      )}
    </section>
  );
}

Render the component from App.jsx:

import NotificationCenter from "./NotificationCenter";

export default function App() {
  return (
    <main>
      <h1>Dashboard</h1>
      <NotificationCenter userId="user-123" />
    </main>
  );
}

The hard-coded user ID is only for local demonstration. A real application should obtain the authenticated user identity from its session or authentication provider.

The React effect creates the connection when the component mounts and closes it when the component unmounts or the userId changes. This cleanup prevents an obsolete connection from continuing to receive messages.

React state is updated using the previous state value. This pattern avoids losing notifications when multiple events arrive close together.

The component also parses incoming messages inside a try...catch block. A malformed message should not crash the notification interface.

7. Adding a Reconnection Strategy

Network interruptions are inevitable. Users switch between Wi-Fi and mobile data, laptops enter sleep mode, and servers may restart during deployments. A production notification system must recover from these interruptions.

The initial React component detects when the connection closes, but it does not reconnect automatically. We can improve it with a retry strategy that waits progressively longer between attempts.

A simple exponential backoff strategy calculates the delay using the number of failed attempts:

\[ delay = \min(baseDelay \times 2^{attempt}, maxDelay) \]

Random jitter can be added to prevent thousands of clients from reconnecting simultaneously after a server outage.

Here is a reusable React hook demonstrating this approach:

import { useEffect, useState } from "react";

export function useNotificationSocket(userId) {
  const [status, setStatus] = useState("disconnected");
  const [messages, setMessages] = useState([]);

  useEffect(() => {
    if (!userId) return;

    let socket;
    let retryTimer;
    let attempts = 0;
    let stopped = false;

    function connect() {
      if (stopped) return;

      setStatus("connecting");

      socket = new WebSocket(
        `ws://localhost:3000/ws?userId=${encodeURIComponent(userId)}`
      );

      socket.onopen = () => {
        attempts = 0;
        setStatus("connected");
      };

      socket.onmessage = (event) => {
        try {
          const data = JSON.parse(event.data);

          if (data.type === "notification") {
            setMessages((previous) => [
              data.payload,
              ...previous,
            ]);
          }
        } catch {
          console.error("Unable to parse socket message");
        }
      };

      socket.onerror = () => {
        setStatus("error");
      };

      socket.onclose = () => {
        if (stopped) return;

        setStatus("disconnected");

        const delay = Math.min(
          1000 * 2 ** attempts,
          30000
        );

        const jitter = Math.random() * 1000;
        attempts += 1;

        retryTimer = setTimeout(
          connect,
          delay + jitter
        );
      };
    }

    connect();

    return () => {
      stopped = true;
      clearTimeout(retryTimer);

      if (socket) {
        socket.close();
      }
    };
  }, [userId]);

  return { status, messages };
}

This hook reconnects after an unexpected disconnection and stops retrying when the component is cleaned up.

The retry delay starts around one second and increases up to approximately thirty seconds, with additional jitter. In a more advanced implementation, retry attempts can be reset after the connection remains healthy for a specified period.

The browser's native WebSocket API does not provide automatic reconnection. Developers must implement it themselves or use a library that offers this feature. See the MDN WebSocket guide.

Important: Reconnection alone does not guarantee that every notification will be received. The application must retrieve missed notifications from persistent storage after reconnecting.

8. Persisting Notifications in a Database

An in-memory notification list is useful for demonstrating the interface, but it has an important limitation: data disappears when the browser reloads or the server restarts.

A real application should store notifications in a database.

For example, a PostgreSQL table might look like this:

CREATE TABLE notifications (
    id UUID PRIMARY KEY,
    recipient_id UUID NOT NULL,
    title VARCHAR(200) NOT NULL,
    message TEXT NOT NULL,
    event_type VARCHAR(100),
    resource_id UUID,
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
    read_at TIMESTAMPTZ
);

CREATE INDEX idx_notifications_recipient_created
ON notifications (recipient_id, created_at DESC);

CREATE INDEX idx_notifications_unread
ON notifications (recipient_id, created_at DESC)
WHERE read_at IS NULL;

Each notification has a unique identifier, a recipient, a title, a message, a creation timestamp, and an optional read timestamp. The resource_id field can connect the notification to an order, project, conversation, or other application record.

The recipient index makes it easier to retrieve notifications for an individual user. The partial index can improve queries that retrieve only unread notifications.

When a business event occurs, the backend should create the notification record before attempting delivery.

A typical flow is:

Validate and process the business action.
Store the business data.
Create the notification record.
Publish a notification event.
Deliver the event to connected clients.
Allow the client to retrieve stored notifications later.

For important workflows, a transactional outbox pattern can help prevent the database record and event publication from becoming inconsistent. The application writes the business change and an outbox event in the same database transaction, then a background worker publishes pending events.

This approach helps avoid situations where a transaction succeeds but the notification event is never published because the process crashes.

9. Loading Existing Notifications Through an HTTP API

WebSockets should handle live updates, while HTTP endpoints can retrieve notification history and manage read states.

For example, an API could provide these endpoints:

Method	Endpoint	Purpose
GET	`/api/notifications`	Retrieve paginated notifications
GET	`/api/notifications/unread-count`	Retrieve the unread count
PATCH	`/api/notifications/:id/read`	Mark a notification as read
PATCH	`/api/notifications/read-all`	Mark all notifications as read

Every endpoint must derive the recipient from the authenticated session or verified access token. It must never trust a user ID supplied by the request as proof of ownership.

When React loads the notification center, it should first retrieve recent notifications through the HTTP API. It can then listen for incoming WebSocket events.

Because a notification could arrive while the initial HTTP request is running, the frontend should merge the results using notification IDs rather than blindly replacing its entire list.

The same principle applies when the user reconnects after being offline: fetch notifications created after the last successfully processed cursor or timestamp.

A timestamp-only cursor may be insufficient when several events share the same timestamp. A stable, unique ordering key or event sequence is preferable for reliable pagination.

10. Implementing Read and Unread States Correctly

Unread counters are among the most visible features of a notification system. However, they can become inaccurate if read state exists only in React memory.

Consider a user who marks a notification as read on a laptop and later opens the application on a mobile device. Both devices should display the same read state.

The backend should therefore own the authoritative notification status.

When the user selects Mark as read, React sends a request to the API. The server verifies that the notification belongs to the authenticated user, updates read_at, and returns the updated record.

The frontend can use optimistic updates to make the interface feel immediate. If the request fails, it should revert the local change or display a retry option.

For a system with several connected devices, the server can also broadcast a notification.read event to the user's other active connections.

A useful event structure is:

{
  "type": "notification.read",
  "payload": {
    "notificationId": "notification-uuid",
    "readAt": "2026-10-20T09:00:00Z"
  }
}

The server must validate every read operation. A notification identifier is not a permission token, and knowing another user's notification ID must not grant access to it.

For bulk updates, use a database transaction where appropriate and return the authoritative unread count or enough information for the client to calculate it consistently.

11. Defining a Consistent Event Protocol

As an application grows, sending arbitrary JSON objects through WebSockets becomes difficult to maintain. Establishing a consistent message format makes the system easier to test and extend.

A notification event could follow this structure:

{
  "type": "notification.created",
  "eventId": "event-uuid",
  "version": 1,
  "occurredAt": "2026-10-20T09:00:00Z",
  "payload": {
    "id": "notification-uuid",
    "title": "New task assigned",
    "message": "A task has been assigned to you.",
    "createdAt": "2026-10-20T09:00:00Z",
    "read": false
  }
}

The type field tells the client which operation to perform. The eventId helps with tracing and deduplication. The version field supports gradual protocol changes.

A client-side event handler can route messages by type:

function handleNotificationEvent(event) {
  switch (event.type) {
    case "notification.created":
      // Add the new notification.
      break;

    case "notification.read":
      // Update the notification's read state.
      break;

    case "notification.deleted":
      // Remove the notification if permitted.
      break;

    default:
      console.warn("Unknown event type:", event.type);
  }
}

In production, validate incoming data against a schema and reject malformed or unsupported messages. Avoid rendering arbitrary server-provided HTML as notification content.

Stable event contracts also make it easier to introduce mobile applications, additional backend services, and alternative delivery channels without redesigning the entire system.

12. Securing WebSocket Connections

Security must be part of the architecture from the beginning.

Use secure transport

Production applications should use wss:// for encrypted WebSocket connections. When a website is served over HTTPS, browsers generally block insecure WebSocket connections from that page.

Authenticate users

The server must authenticate each connection using a verified session or token. It should derive the user identity from trusted authentication information rather than accepting an arbitrary userId query parameter.

Query parameters can appear in logs and monitoring systems. Avoid placing long-lived secrets in WebSocket URLs. Depending on the architecture, a secure session cookie, a short-lived single-use connection ticket, or an appropriate authentication handshake may be preferable.

Authorize every event

Authentication establishes who the user is; authorization determines what they may access. The server must ensure that a notification is delivered only to its intended recipient and that incoming actions affect only resources the user is allowed to access.

Validate origins

Validate the Origin header against an explicit allowlist when serving browser clients. Origin checks are particularly important when cookies authenticate connections, but they are not a replacement for authentication.

Validate payloads and limit message sizes

Reject malformed JSON, unexpected event types, oversized messages, and unsupported operations. Apply rate limits to connection attempts and incoming messages.

Protect sensitive information

Notifications should contain only the information necessary for the user to understand the event. Sensitive financial, personal, or account data should be retrieved through appropriately authorized API endpoints.

Plan for expired sessions

If a user's session expires or access is revoked, close or reauthorize existing WebSocket connections. A connection that was valid when first opened should not remain trusted indefinitely.

The MDN WebSocket client guide provides additional guidance on connection handling and security considerations.

13. Scaling Beyond a Single Server

The in-memory Map used in our demonstration works for one server process. However, it creates a problem when the application runs across multiple instances.

Imagine that a user connects to server A, while an event is processed by server B. Server B cannot see server A's local connection map. Without additional coordination, the notification may never reach the connected client.

A distributed architecture can solve this problem using a message broker such as Redis Pub/Sub or a durable event streaming platform.

The flow becomes:

An application service creates a notification.
The notification is persisted in the database.
An event is published to a broker.
WebSocket server instances subscribe to relevant events.
The instance holding the recipient's connection delivers the notification.

For larger systems, a broker with durable retention and consumer acknowledgments can help with reliable processing. Redis Pub/Sub provides lightweight message distribution but does not itself guarantee that disconnected subscribers will receive missed messages.

Regardless of the broker, the database remains the source of truth for notification history.

Horizontal scaling also requires attention to connection limits, memory usage, heartbeat handling, reverse-proxy timeouts, and load-balancer configuration. WebSocket connections are long-lived, so infrastructure must be configured to support them.

Sticky sessions may be needed in some architectures, but they do not replace cross-instance event distribution.

14. Handling Duplicate and Missing Notifications

Networks and distributed systems can deliver the same event more than once. Events may also be delayed, arrive out of order, or be missed during disconnections.

A robust system should be designed around these possibilities.

Deduplication: Store or track processed notification IDs and ignore duplicates when merging the list.

Persistence: Save notifications before delivery so that reconnecting clients can retrieve them.

Catch-up synchronization: After reconnecting, request notifications created since the last confirmed cursor.

Ordering: Use stable event identifiers and sequence numbers when ordering is important.

Acknowledgments: For critical workflows, define an acknowledgment protocol and retry policy. A WebSocket send() call alone does not prove that the recipient processed or displayed the notification.

Idempotency: Make repeated operations safe. For example, marking an already-read notification as read should not create an inconsistent state.

The appropriate delivery guarantee depends on the product. A casual social reaction may tolerate a small delay, while a financial transaction alert requires stronger persistence, auditability, and recovery behavior.

15. Improving Frontend Performance

A notification center may eventually receive hundreds or thousands of events. React rendering and memory usage should be considered as early as possible.

Useful optimization techniques include:

Limit the number of notifications kept in active component state.
Retrieve older notifications through pagination.
Virtualize long lists to avoid rendering every row simultaneously.
Batch related state updates where appropriate.
Use stable notification IDs as React keys.
Avoid creating a separate WebSocket connection for every notification component.
Deduplicate events before adding them to state.
Keep notification rendering lightweight.

The standard browser WebSocket API does not provide automatic backpressure. If messages arrive faster than the application can process them, memory usage and responsiveness may suffer. The MDN WebSocket documentation discusses this limitation.

For high-volume systems, consider server-side filtering, bounded client queues, event batching, message coalescing, and flow-control strategies.

For example, an application dashboard may not need to render every intermediate progress update. It can keep only the latest progress value while preserving important events in persistent storage.

16. Testing the Notification System

Testing should cover both the expected workflow and failure scenarios.

Unit testing

Test notification reducers, event parsers, deduplication logic, unread counts, and read-state updates independently of the WebSocket server.

Integration testing

Start the backend and connect a test client. Verify that a notification created for user A reaches user A but not user B.

Reconnection testing

Disconnect the client, create notifications, reconnect, and confirm that the HTTP catch-up process retrieves missed events.

Authorization testing

Attempt to read another user's notification, mark another user's notification as read, and connect without valid authentication. All such attempts should be rejected.

Load testing

Simulate many concurrent connections and bursts of events. Measure delivery latency, CPU utilization, memory consumption, connection failures, and database performance.

Browser testing

Verify behavior during navigation, page refreshes, temporary network failures, session expiration, and multiple browser tabs.

React's development Strict Mode may run an additional setup-and-cleanup cycle for effects. Ensure that socket cleanup is correct and that the application does not accumulate unnecessary connections during development.

17. Monitoring and Production Deployment

A system that works locally may fail under real traffic unless it is monitored and deployed correctly.

Track metrics such as:

Active WebSocket connections.
Successful and failed connection attempts.
Notification delivery latency.
Reconnection frequency.
Broker queue depth and processing delays.
Database query duration.
Invalid messages and authorization failures.

Use structured logs and correlation IDs to trace a notification from the original business event to database persistence, broker publication, WebSocket delivery, and client acknowledgment.

Do not log authentication tokens or sensitive notification payloads.

For deployment, configure a reverse proxy or load balancer to support WebSocket upgrades and long-lived connections. Ensure that proxy timeouts are appropriate, and implement heartbeat or ping/pong mechanisms to detect stale connections.

Configure environment variables for service URLs, authentication settings, and database credentials. Secrets should be managed through an appropriate secrets-management system rather than committed to source control.

Finally, use health checks and graceful shutdown procedures. When a server instance is about to stop, it should stop accepting new connections, notify clients when possible, close existing connections cleanly, and allow clients to reconnect to a healthy instance.

18. Common Mistakes to Avoid

Several implementation mistakes can undermine a real-time notification system.

Using WebSockets without persistence: Users may lose access to important events after refreshing the browser.

Trusting client-provided user IDs: This can expose notifications to unauthorized users.

Ignoring cleanup: Old connections may remain active after a React component unmounts or its user changes.

Assuming delivery is guaranteed: A successful connection does not guarantee that every event was received and processed.

Creating too many connections: Multiple components opening independent sockets can waste server resources.

Skipping reconnect synchronization: Reconnecting without fetching missed events leaves gaps in notification history.

Ignoring cross-instance delivery: Local in-memory connection tracking is insufficient for a multi-server deployment.

Sending sensitive information through notification payloads: Excessive data increases the impact of accidental exposure.

Addressing these issues early can prevent expensive architectural changes later.

Conclusion

Building a real-time notification system with React and WebSockets is an excellent way to improve the responsiveness of modern web applications. WebSockets provide a persistent communication channel, while React makes it straightforward to render incoming events and update notification counts.

However, a production-ready solution requires more than opening a socket and displaying a message. It needs authenticated connections, authorization checks, persistent notification records, reconnection handling, duplicate protection, missed-event recovery, and a scalable event-distribution architecture.

A practical development path is to begin with a single WebSocket server and React notification component, introduce database persistence, add HTTP endpoints for notification history and read states, and then implement distributed messaging when scaling demands it.

By combining these practices, developers can build notification systems that remain responsive, secure, maintainable, and reliable as an application grows.

Whether you are developing a project management dashboard, an e-commerce platform, a customer relationship management system, or a collaborative workspace, the same core principles apply: persist important events, deliver them efficiently, authorize every operation, and design for interruptions from the beginning.

🔥 30 Days of Frontend — Day 5: React DevTools Profiler

Sat, 17 Oct 2026 16:39:44 +0000

When a React application starts feeling slow, one of the first things developers often do is reach for useMemo, useCallback, or React.memo.

We've all seen this pattern:

A component renders more often than expected.
The UI feels sluggish when interacting with a page.
A large list becomes noticeably slower as more items are added.
Updating one piece of state seems to trigger work across an entire component tree.

The natural reaction is to start memoizing components and functions.

But here's the problem: you might be optimizing code that isn't responsible for the slowdown in the first place.

React performance optimization should start with understanding what is happening, not guessing what might be happening.

That's where the React DevTools Profiler becomes useful.

1. What Is the React DevTools Profiler?

React DevTools is a browser extension that helps developers inspect React component trees, props, state, and other component-related information.

It includes two particularly useful panels:

Components: Inspect the component hierarchy, props, state, and component details.
Profiler: Record rendering activity and investigate how React updated the component tree.

The Profiler helps you understand the rendering work associated with a particular interaction.

For example, imagine you're working on an e-commerce application with a product grid containing hundreds of products.

When a user changes a filter, several things might happen:

The parent component updates.
The product list renders again.
Individual product cards render.
Sorting or filtering calculations run.
Some components render even though their visible data hasn't changed.

Some of this work might be necessary. Some might be avoidable.

Instead of assuming which component is responsible, you can record the interaction and inspect the results.

The goal isn't to eliminate every render. It's to understand whether the work is necessary and whether it affects the user experience.

2. Understanding How React Rendering Relates to Profiling

Before opening the Profiler, it's worth understanding what it actually measures.

A React update generally involves two important phases.

The render phase

During the render phase, React calls components as needed to determine what the next UI should look like.

This phase includes calculating the next React element tree and determining the changes required.

A component rendering doesn't automatically mean that the browser DOM will change.

For example:

function Counter({ count }) {
  console.log("Counter rendered");

  return <p>Count: {count}</p>;
}

Whenever React calls Counter, the component function executes and returns a React element describing the UI.

React may then determine that the resulting output doesn't require a DOM mutation.

A render is not the same thing as a DOM update.

This distinction is important because developers sometimes interpret every component render as expensive browser work.

The commit phase

After React finishes the necessary render work, it can commit the changes to the host environment, such as updating the DOM in a browser.

The Profiler helps you investigate rendering activity, but its measurements shouldn't be interpreted as a complete measurement of every part of browser performance.

For example, a page can have relatively inexpensive React rendering but still feel slow because of:

Expensive JavaScript outside React.
Large amounts of DOM layout or painting.
Long-running event handlers.
Network delays.
Large images or other resources.
Main-thread work that blocks user interactions.

This is why the React Profiler is one tool in a broader performance investigation, not a replacement for the browser's Performance panel.

3. What Can You Learn From the Profiler?

When you record a profiling session, the Profiler provides several useful ways to understand React's work.

A. Which components rendered?

The Profiler helps you identify the components involved in an update.

Suppose your component tree looks like this:

App
├── Header
├── SearchBar
├── FilterSidebar
└── ProductGrid
    ├── ProductCard
    ├── ProductCard
    ├── ProductCard
    └── ...

When the user types into the search field, you might discover that SearchBar, ProductGrid, and many ProductCard instances rendered.

That doesn't automatically mean all those renders are unnecessary.

You need to understand why they rendered and whether the work was expensive.

The component tree gives you a starting point for that investigation.

B. How often did components render?

Repeated rendering can be perfectly normal.

For example, typing into a controlled input typically updates state as the user types:

function SearchBar() {
  const [query, setQuery] = React.useState("");

  return (
    <input
      value={query}
      onChange={(event) => {
        setQuery(event.target.value);
      }}
      placeholder="Search products..."
    />
  );
}

Each keystroke can trigger an update.

That's expected behavior.

The more interesting question is what else happens during those updates.

If typing into the search field also triggers expensive calculations or unnecessary rendering across a large product grid, the Profiler can help you investigate that work.

Render frequency is a clue, not a performance verdict.

C. What caused a component to render?

This is one of the most useful parts of profiling.

A component might render because:

Its state changed.
Its parent rendered.
Its props changed.
Its context value changed.
An external store or another subscription triggered an update.

The exact cause depends on the component and the update mechanism.

For example:

function ProductPage() {
  const [query, setQuery] = React.useState("");
  const [selectedCategory, setSelectedCategory] =
    React.useState("all");

  return (
    <>
      <SearchInput
        value={query}
        onChange={setQuery}
      />

      <CategoryFilter
        value={selectedCategory}
        onChange={setSelectedCategory}
      />

      <ProductGrid query={query} />
    </>
  );
}

When selectedCategory changes, ProductPage renders again.

Because ProductGrid is a child of ProductPage, React may also render ProductGrid, even though its query prop hasn't changed.

That can be a candidate for optimization, but it isn't automatically a problem. First, determine whether the work is expensive enough to matter.

Also, remember that React DevTools' ability to display detailed render reasons depends on the React version, development tooling, and available settings. Don't assume every render will always have a definitive explanation displayed.

4. How to Use React DevTools Profiler: A Step-by-Step Workflow

Let's turn this into a practical workflow.

Step 1: Reproduce the actual performance problem

Start with the user interaction that feels slow.

Examples include:

Typing into a search field.
Changing a product filter.
Switching tabs.
Expanding a large navigation menu.
Updating a dashboard with multiple charts.
Scrolling through a long list.

Avoid profiling random interactions without a clear question.

A useful starting question might be:

Why does changing a product filter cause so much rendering work?

This gives you a specific behavior to investigate.

Step 2: Open React DevTools

Install React Developer Tools for your browser if you haven't already.

Open your application, launch the browser's developer tools, and locate the Profiler tab.

Make sure you're profiling the application and interaction you want to investigate.

For realistic performance measurements, prefer a production build or a profiling-enabled production build where appropriate. Development mode can introduce extra overhead, and Strict Mode may intentionally invoke rendering-related logic more than once to help reveal bugs.

Development profiling is still valuable for understanding component behavior, but don't assume its timings represent production performance.

Step 3: Start recording

In the Profiler tab, start a recording.

Then perform the exact interaction that causes the slowdown.

For example:

Start recording.
Type a search query.
Change a category filter.
Wait for the UI to settle.
Stop recording.

Keep the recording focused.

Step 4: Inspect the recorded commits

The Profiler organizes recorded updates into commits.

A commit represents a point at which React applied an update to the host environment

Select a commit related to your interaction, then inspect the available visualization and component details.

Look for patterns such as:

A large subtree rendering during a small interaction.
An expensive component repeatedly appearing in relevant commits.
Components rendering even though their inputs appear unchanged.
Expensive calculations associated with frequently occurring updates.

Don't immediately optimize the component with the largest-looking bar. First establish what the measurement represents and whether that component is related to the user-visible problem.

Step 5: Make one targeted change

Change one thing at a time whenever possible.

If you simultaneously add React.memo, introduce several useMemo calls, restructure the component tree, and change how state is managed, you won't know which change made the difference.

A focused experiment makes the results easier to interpret.

Step 6: Profile again

Repeat the same interaction under comparable conditions.

Compare:

Actual rendering duration.
Which components rendered.
How much of the subtree participated in the update.
Whether the interaction feels more responsive.
Whether the optimization introduced additional complexity or bugs.

If the measured React work decreased but the interaction still feels slow, investigate other parts of the performance pipeline.

An optimization isn't complete until you've verified its effect.

The React DevTools Profiler helps turn vague performance complaints into concrete questions about rendering behavior.

Instead of asking:

"Why is React so slow?"

Start by asking:

"Where is my application actually spending time, and what evidence do I have?"

That shift—from guessing to measuring—is what makes performance optimization more systematic.

How to Build a Lead Management Dashboard from Scratch

Fri, 16 Oct 2026 13:24:35 +0000

In today's competitive digital business environment, generating leads is only the first step toward acquiring customers. Businesses also need an effective way to organize prospects, track communication, monitor sales activities, and measure conversion rates. Without a centralized system, important leads can get lost, follow-ups may be delayed, and sales opportunities can disappear.

A lead management dashboard solves these problems by bringing essential customer and sales information into one organized interface. It helps sales representatives, marketing teams, business owners, and customer relationship managers understand what is happening throughout the sales pipeline.

Building a lead management dashboard from scratch is an excellent full-stack development project because it combines frontend design, backend development, database management, authentication, data visualization, and business logic.

In this article, we will explore how to plan, design, develop, secure, test, and deploy a lead management dashboard using modern web technologies such as React, FastAPI, PostgreSQL, and supporting tools.

By the end, you will understand the architecture and essential features needed to build a practical lead management application.

1. What Is a Lead Management Dashboard?

A lead management dashboard is a centralized web application that allows businesses to manage potential customers from their initial interaction through qualification, follow-up, and conversion.

A lead may come from a website contact form, social media campaign, paid advertisement, email subscription, referral, or direct sales inquiry.

The dashboard stores this information and makes it accessible to authorized team members.

For example, imagine a digital marketing agency receiving 200 leads each month from Google Ads, Facebook campaigns, and its website. Managing every prospect manually through spreadsheets can quickly become confusing.

A lead management dashboard helps the agency:

Store lead information in one place.
Identify the source of each lead.
Assign leads to sales representatives.
Track follow-up activities.
Monitor lead status and sales progress.
Measure campaign performance.
Identify leads that need immediate attention.
Generate reports for business decisions.

Unlike a simple contact list, a lead management dashboard focuses on the complete process of turning prospects into customers.

2. Define the Project Requirements

Before writing code, establish what the application should accomplish. Clear requirements prevent unnecessary complexity and help developers prioritize the features that deliver the most value.

For the first version, focus on a minimum viable product (MVP).

Essential features

Lead management: Users should be able to create, view, edit, and delete lead records according to their permissions.

Dashboard statistics: Display total leads, new leads, qualified leads, converted leads, and other relevant metrics.

Sales pipeline: Organize prospects into stages such as New, Contacted, Qualified, Proposal, Won, and Lost.

Search and filtering: Allow users to find leads by name, email, source, status, or assigned sales representative.

Task and follow-up management: Record upcoming calls, meetings, emails, and reminders.

Lead assignment: Assign prospects to individual sales representatives or teams.

Reports and analytics: Visualize lead sources, conversion rates, and changes in lead volume over time.

Authentication and authorization: Ensure that users can access only the features and records permitted by their roles.

Advanced features

Once the core application works reliably, consider adding email integrations, automated notifications, CSV imports and exports, duplicate detection, lead scoring, and marketing platform integrations.

Starting with a manageable scope is better than attempting to build an entire enterprise CRM in the first release.

3. Choose the Technology Stack

Selecting the right technology stack affects development speed, performance, maintainability, and scalability.

For this project, React, FastAPI, and PostgreSQL provide a practical combination.

Frontend: React

React is a JavaScript library for building interactive user interfaces. It allows developers to create reusable components for dashboard cards, tables, filters, forms, and charts.

Useful supporting tools include:

React Router for page navigation.
Axios or the Fetch API for HTTP requests.
Recharts for data visualization.
React Hook Form for form management.
Tailwind CSS for responsive styling.

Backend: FastAPI

FastAPI is a Python framework for developing APIs. It supports request validation, asynchronous endpoints, automatic API documentation, and integration with Python libraries.

It can handle lead creation, authentication, filtering, reporting, assignment, and other business operations.

Database: PostgreSQL

PostgreSQL is a relational database suitable for structured business data. It supports relationships, transactions, indexing, constraints, and advanced queries.

These features are important when leads belong to organizations, sales representatives own leads, and activities reference individual prospects.

Additional tools

Consider using SQLAlchemy for database access, Alembic for schema migrations, Pydantic for validation, pytest for automated testing, Git for version control, and Docker for consistent deployment environments.

The objective is not to use every available library. Choose tools that solve specific project requirements.

4. Design the Application Architecture

A clean architecture separates the user interface, business logic, and data storage.

A typical request follows this path:

A user interacts with the React dashboard.
React sends an HTTP request to the FastAPI backend.
FastAPI validates the request and checks the user's permissions.
The backend executes the required business logic.
SQLAlchemy communicates with PostgreSQL.
The backend returns a structured JSON response.
React updates the dashboard with the latest information.

For example, when a sales representative creates a new lead, the frontend submits the form data to an API endpoint. The backend validates the information, associates the record with the appropriate organization, saves it in PostgreSQL, and returns the newly created lead.

The frontend then updates the lead table and relevant statistics.

Separating these responsibilities makes the application easier to maintain, test, and extend.

5. Plan the Database Schema

Database design is one of the most important steps in building a reliable lead management system.

A poorly designed schema can produce duplicate records, inconsistent statuses, slow queries, and difficult reporting.

Start by identifying the main entities.

Leads table

The leads table stores prospect information.

Recommended fields include:

id: Unique lead identifier.
first_name: Prospect's first name.
last_name: Prospect's last name.
email: Email address.
phone: Contact number.
company: Company name.
source: Origin of the lead.
status: Current sales stage.
assigned_to: Assigned user identifier.
organization_id: Organization that owns the record.
created_at: Creation timestamp.
updated_at: Last modification timestamp.

Users table

The users table stores employee or account information.

Typical fields include a unique identifier, name, email address, password hash, role, organization identifier, and account status.

Never store passwords as plain text.

Activities table

An activities table records interactions associated with leads.

Its fields may include the lead identifier, activity type, description, scheduled time, completion status, creator, and creation timestamp.

Examples of activities include phone calls, email conversations, meetings, and follow-up tasks.

Organizations table

If the dashboard serves multiple businesses, create an organizations table. Every relevant record should be associated with the correct organization.

This helps prevent one company's users from accessing another company's customer information.

Campaigns table

A campaigns table can store marketing campaign names, channels, budgets, and external identifiers. Leads can reference campaigns to support more detailed attribution reporting.

Use foreign keys to maintain relationships and database constraints to enforce important rules.

6. Create the Backend Project

Begin by creating a dedicated backend directory.

A simple project structure could look like this:

backend/
├── app/
│   ├── main.py
│   ├── database.py
│   ├── models.py
│   ├── schemas.py
│   ├── auth.py
│   ├── dependencies.py
│   └── routers/
│       ├── leads.py
│       ├── users.py
│       ├── activities.py
│       └── analytics.py
├── tests/
├── alembic/
├── requirements.txt
└── .env

This structure separates API endpoints from database models, validation schemas, and authentication logic.

Install FastAPI, Uvicorn, SQLAlchemy, a PostgreSQL driver, Pydantic settings, and the authentication libraries you choose.

Create the FastAPI application in main.py:

from fastapi import FastAPI
from app.routers import leads, users, activities, analytics

app = FastAPI(title="Lead Management API")

app.include_router(leads.router, prefix="/api/leads")
app.include_router(users.router, prefix="/api/users")
app.include_router(
    activities.router,
    prefix="/api/activities"
)
app.include_router(
    analytics.router,
    prefix="/api/analytics"
)

@app.get("/health")
def health_check():
    return {"status": "healthy"}

This example assumes each router module exports a configured router object.

The health endpoint provides a simple way to verify that the backend is running.

Keep configuration values such as database credentials in environment variables rather than hardcoding them into source files.

7. Connect PostgreSQL to FastAPI

Create a PostgreSQL database for the application and configure its connection string through an environment variable.

SQLAlchemy can manage database connections and transactions.

A simplified database setup might look like this:

import os
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

DATABASE_URL = os.environ["DATABASE_URL"]

engine = create_engine(
    DATABASE_URL,
    pool_pre_ping=True
)

SessionLocal = sessionmaker(
    bind=engine,
    autoflush=False,
    expire_on_commit=False
)

In production, choose an appropriate connection pool size and configure database timeouts according to the hosting environment.

Create a FastAPI dependency that provides a database session for each request and reliably closes it afterward.

Use Alembic to manage schema changes. Avoid relying on automatic table creation as your only production migration strategy.

8. Build the Lead API

The backend should expose endpoints that represent the core operations of the application.

A practical API design might include:

Method	Endpoint	Purpose
GET	`/api/leads`	List and filter leads
POST	`/api/leads`	Create a lead
GET	`/api/leads/{id}`	Retrieve one lead
PATCH	`/api/leads/{id}`	Update lead details
DELETE	`/api/leads/{id}`	Delete or archive a lead
GET	`/api/analytics/summary`	Retrieve dashboard statistics

Use Pydantic schemas to validate incoming data and control which fields appear in responses.

For example, a lead creation schema could look like this:

from pydantic import BaseModel, EmailStr
from typing import Optional

class LeadCreate(BaseModel):
    first_name: str
    last_name: str
    email: EmailStr
    phone: Optional[str] = None
    company: Optional[str] = None
    source: str = "Website"

Additional validation should check allowed source values, required fields, field lengths, and business-specific rules.

Do not allow a client to choose arbitrary ownership or organization identifiers without verifying authorization on the server.

Implement lead creation

The create endpoint should:

Authenticate the user.
Validate the submitted fields.
Determine the organization from the authenticated user's context.
Apply the correct assignment rules.
Save the record within a database transaction.
Return the created lead using a response schema.

Return appropriate HTTP status codes. For example, a successful creation typically returns 201 Created, invalid input returns 422 Unprocessable Entity, and an unauthorized request may return 401 Unauthorized or 403 Forbidden.

Implement filtering and pagination

As the database grows, returning every lead in a single request becomes inefficient.

Support query parameters such as:

GET /api/leads?status=Qualified&page=1&page_size=20

The backend should apply filters before pagination, enforce a reasonable maximum page size, and use deterministic sorting.

For larger datasets, consider cursor-based pagination.

9. Implement Authentication and Role-Based Access

A lead management dashboard often contains personal information, customer communications, and commercially sensitive data.

Authentication determines who the user is. Authorization determines what that user can do.

Common roles include:

Administrator: Manages organization settings and users.
Sales manager: Views team performance and assigns leads.
Sales representative: Manages assigned prospects and follow-ups.
Marketing analyst: Reviews campaign sources and permitted analytics.

These roles are examples; actual permissions should reflect the business requirements.

Use a well-established authentication approach, such as secure server-managed sessions or carefully implemented OAuth2-based authentication.

If using JWTs, validate token signatures, expiration, issuer, and audience where applicable. Use secure password hashing such as Argon2id or an appropriately configured bcrypt implementation.

For browser applications, secure, HTTP-only cookies can reduce exposure to token theft through JavaScript, but cookie-based authentication also requires appropriate CSRF protections.

Most importantly, authorization checks must happen on the backend. Hiding a button in React does not prevent a user from directly calling the API.

Every query involving a lead should enforce organization and user access restrictions.

10. Build the React Dashboard Interface

Once the API is available, build a responsive frontend that makes sales information easy to understand.

A useful dashboard layout includes:

A sidebar for navigation.
A top navigation bar with search and account controls.
Summary cards for important metrics.
A sales pipeline overview.
A recent leads table.
A follow-up activity panel.
Charts for sources and conversion performance.

Suggested pages include Dashboard, Leads, Pipeline, Activities, Reports, Team, and Settings.

Use reusable components instead of building every page independently.

For example:

src/
├── components/
│   ├── Sidebar.jsx
│   ├── Header.jsx
│   ├── MetricCard.jsx
│   ├── LeadTable.jsx
│   ├── LeadForm.jsx
│   └── StatusBadge.jsx
├── pages/
│   ├── Dashboard.jsx
│   ├── Leads.jsx
│   ├── Pipeline.jsx
│   └── Reports.jsx
├── services/
│   └── api.js
├── hooks/
├── App.jsx
└── main.jsx

Keep API communication in a dedicated service layer. This prevents request logic from becoming scattered throughout the user interface.

The dashboard should provide clear loading indicators, helpful error messages, empty states, and confirmation messages after successful actions.

11. Create Dashboard Metric Cards

Metric cards provide an immediate overview of sales activity.

Useful metrics include:

Total leads: The number of accessible lead records.

New leads: Prospects created during a selected reporting period.

Qualified leads: Prospects that meet the organization's qualification criteria.

Converted leads: Prospects that have become customers or reached the defined Won stage.

Pending follow-ups: Incomplete follow-up activities that are due or overdue.

Each metric should have a clearly defined calculation.

For example, if a business has 500 leads and 50 have converted, its simple lead conversion rate is:

Conversion rate = (Converted leads ÷ Total leads) × 100

In this example, the rate is 10%.

However, the denominator matters. A conversion rate calculated from all historical leads differs from a rate calculated only from leads created during a specific month.

For accurate analysis, define the reporting period, time zone, lead population, and conversion event.

Avoid presenting numbers without explaining their meaning.

12. Build Data Visualization and Analytics

Charts help users identify patterns that may not be obvious in tables.

Consider adding the following visualizations.

Leads by source

A bar chart can compare leads generated by website forms, Google Ads, Facebook Ads, referrals, and other channels.

This allows marketers to understand which sources contribute the most prospects.

Lead pipeline

A funnel or horizontal bar chart can show how many leads are in each stage.

For example:

New: 120
Contacted: 85
Qualified: 50
Proposal: 25
Won: 12

These numbers are illustrative. Real dashboards should calculate values directly from the database.

Conversion trends

A line chart can show how conversion counts or rates change over time. This helps managers compare reporting periods and evaluate the effects of marketing campaigns.

Sales representative performance

A report can compare assigned leads, completed follow-ups, qualified prospects, and conversions across team members.

Use consistent metric definitions and ensure that users can see only the performance data they are authorized to access.

Charts should include readable labels, useful tooltips, accessible colors, and alternative text or tabular data where appropriate.

13. Connect React to the Backend API

React needs a reliable way to communicate with FastAPI.

Create a shared API client that defines the backend base URL, request defaults, and common error handling.

A basic Fetch API request might look like this:

const response = await fetch(
  `${API_URL}/api/leads?page=1&page_size=20`,
  {
    credentials: "include",
  }
);

if (!response.ok) {
  throw new Error("Unable to load leads");
}

const leads = await response.json();

This example assumes cookie-based authentication and an appropriately configured backend. If the application uses bearer tokens, include the authorization header using the chosen secure token-management strategy.

When developing locally, configure CORS to allow only the frontend origins that need access. CORS is not an authentication mechanism and does not replace server-side permission checks.

For larger applications, consider a data-fetching library that supports caching, retries, request deduplication, and cache invalidation.

After a lead is created or updated, refresh the affected list and statistics so the dashboard stays consistent.

14. Add Lead Search and Advanced Filtering

A dashboard becomes significantly more useful when users can locate the right prospect quickly.

Implement filters for:

Lead status.
Lead source.
Assigned sales representative.
Creation date.
Company.
Follow-up date.

Combine filters with keyword search.

For example, a sales manager might search for qualified leads from Facebook Ads created during the current month.

The frontend should send filter parameters to the backend rather than downloading the entire database and filtering everything in the browser.

Use database indexes on frequently queried columns where measurements justify them. For text search, PostgreSQL offers several options, including case-insensitive matching and full-text search.

Debounce keyword input to avoid sending a request for every keystroke.

Also, make filters visible and easy to clear. Users should be able to understand why a particular result appears in the table.

15. Create the Sales Pipeline

The sales pipeline represents the journey from a new prospect to a completed sale.

A common workflow includes:

New.
Contacted.
Qualified.
Proposal Sent.
Won.
Lost.

Organizations should customize these stages according to their actual sales process.

When a representative changes a lead's status, the backend should validate whether the transition is allowed and record the change.

A lead history table can preserve the previous status, new status, user who made the change, and timestamp.

This history supports reporting and helps managers understand how opportunities move through the pipeline.

A drag-and-drop interface can improve usability, but it should call the same validated backend endpoint as a normal status-editing form.

Do not rely on frontend restrictions alone to enforce workflow rules.

16. Add Follow-Up Tasks and Reminders

Many sales opportunities are lost because representatives forget to follow up.

A follow-up module helps prevent this problem by associating tasks with leads.

Each task may contain:

Lead identifier.
Activity type.
Task description.
Due date and time.
Assigned user.
Completion status.
Creation timestamp.

The dashboard can display upcoming tasks and highlight overdue activities.

For example, a representative may see a reminder to call a qualified prospect tomorrow morning.

For automatic reminders, use a background job system or a scheduled worker. Avoid relying on a browser tab remaining open to execute important scheduled tasks.

Notifications can initially appear inside the dashboard. Later, email or other supported notification channels can be integrated.

When sending reminders, handle retries carefully to avoid delivering duplicate messages.

17. Implement Lead Assignment

Lead assignment distributes incoming prospects among sales representatives.

The simplest implementation allows managers to assign leads manually.

More advanced systems can use rules such as:

Round-robin assignment.
Assignment based on product category.
Assignment by region.
Assignment based on representative workload.
Assignment according to lead source.

For example, a round-robin system distributes new leads among eligible representatives in sequence.

A production implementation must account for simultaneous incoming leads, inactive users, and assignment failures. Database transactions or suitable locking strategies can help prevent multiple requests from incorrectly assigning the same sequence position.

Keep assignment rules transparent so managers understand why a prospect was assigned to a particular representative.

18. Build Reporting and Campaign Attribution

Marketing teams need to understand not only how many leads they generate but also how those leads perform.

Store source and campaign information when a lead enters the system.

Where appropriate, capture UTM parameters such as:

utm_source
utm_medium
utm_campaign
utm_content
utm_term

Preserve attribution information according to a documented policy. First-touch attribution, last-touch attribution, and multi-touch attribution answer different questions.

A dashboard can report leads by source, qualified leads by campaign, conversion rates, and cost per lead when reliable cost data is available.

Cost per lead is calculated as:

Cost per lead = Marketing spend ÷ Leads generated

For example, a campaign spending $1,000 and generating 200 leads has a cost per lead of $5.

However, inexpensive leads are not necessarily valuable leads. Comparing qualified-lead rates and eventual revenue can produce better marketing decisions.

Avoid attributing conversions to campaigns without a consistent methodology and adequate tracking data.

19. Improve Performance as the Dataset Grows

A dashboard that performs well with 100 records may become slow when it contains hundreds of thousands of leads and activities.

Performance should be measured before optimization, but several practices provide a strong starting point.

Database optimization

Use indexes for common filters and joins. Review slow queries with PostgreSQL's query-planning tools. Avoid fetching columns that the current page does not need.

Efficient API responses

Use pagination, limit response sizes, and avoid unnecessary database queries.

Be careful with ORM relationships that can generate an excessive number of queries. Eager loading or carefully designed aggregate queries may improve performance.

Frontend optimization

Render only the data needed for the current page. Consider table virtualization for exceptionally large lists.

Use code splitting when the application contains many pages, and avoid recalculating expensive derived values on every render.

Caching

Cache suitable, frequently requested information when doing so provides a measurable benefit.

Analytics caching must account for updates, permissions, and reporting periods. Never share cached user-specific results across organizations.

20. Secure the Application

Security should be part of the initial architecture rather than a final checklist.

A lead dashboard may store names, email addresses, telephone numbers, company details, and sales notes.

Important security measures include:

Enforce authentication and authorization on every protected API.
Scope database queries to the correct organization.
Hash passwords using established algorithms.
Use HTTPS in production.
Store secrets in environment variables or a secret manager.
Validate and normalize input.
Apply rate limits to sensitive endpoints.
Protect cookie-based authentication against CSRF.
Configure appropriate security headers.
Avoid exposing internal errors and stack traces.
Restrict access to exports and reports.
Keep dependencies updated.
Record important administrative and data-access events when appropriate.

SQLAlchemy parameterizes normal query operations, but developers should still avoid unsafe raw SQL construction.

Prevent mass-assignment vulnerabilities by explicitly controlling which fields users can update.

Establish retention and deletion policies for customer information. Depending on where the business operates and where its customers are located, applicable privacy requirements may include the GDPR or other local data-protection laws.

Security is an ongoing responsibility that includes code review, testing, monitoring, and incident response.

21. Make the Dashboard Responsive and Accessible

Sales teams may use the dashboard on desktops, laptops, tablets, and mobile phones.

A responsive layout should adapt to different screen widths without making important actions difficult to reach.

On smaller screens, collapse the sidebar into a navigation menu and allow wide tables to scroll horizontally or switch to a compact card layout.

Accessibility is equally important.

Use semantic HTML, properly labeled form fields, keyboard-accessible controls, visible focus indicators, and sufficient color contrast.

Do not communicate lead status through color alone. Pair status colors with descriptive labels.

Provide clear validation messages when users submit incomplete or invalid forms.

Charts should communicate their meaning without requiring users to distinguish subtle colors. Where possible, provide equivalent data tables.

A dashboard that is accessible and responsive is easier for more people to use effectively.

22. Test the Application Thoroughly

Testing verifies that the dashboard behaves correctly under normal conditions and unexpected situations.

Backend tests

Use pytest to test API endpoints, validation rules, permissions, and business logic.

Examples include verifying that a valid lead can be created, invalid email addresses are rejected, unauthorized users cannot access restricted records, and status changes follow the defined workflow.

Frontend tests

Use tools such as Vitest and React Testing Library to test forms, filters, navigation, loading states, and error handling.

Integration tests

Verify that the frontend, backend, and database work together correctly.

For example, create a lead through the API and confirm that it appears in the filtered lead list and contributes to the appropriate dashboard metric.

End-to-end tests

Playwright can simulate a complete user journey:

Sign in.
Open the leads page.
Create a prospect.
Assign the prospect.
Schedule a follow-up.
Update the lead's status.
Verify the updated dashboard.

Also test empty datasets, duplicate submissions, expired sessions, slow network connections, and concurrent updates.

Use a separate test database and avoid running destructive tests against production data.

23. Deploy the Application

Once the application has passed its tests, prepare it for deployment.

A typical production architecture includes a React frontend, a FastAPI application server, a managed PostgreSQL database, and secure HTTPS access.

Possible deployment options include static frontend hosting, a container platform for FastAPI, and a managed PostgreSQL service.

Docker can package the backend and its dependencies consistently. A production setup should also define health checks, restart policies, resource limits, and appropriate logging.

Before deploying:

Configure production environment variables.
Set up the production database.
Run database migrations.
Build and deploy the React frontend.
Deploy the FastAPI application.
Configure the correct frontend origins and API URL.
Enable HTTPS.
Create a database backup policy.
Test authentication and organization-level permissions.
Verify logging, monitoring, and error reporting.

Do not expose PostgreSQL directly to the public internet unless there is a carefully justified and secured requirement.

Run database migrations as a controlled deployment step. For changes that may affect existing records, use a migration strategy that supports safe rollout and recovery.

A successful deployment means more than opening the homepage. Users must be able to authenticate, create leads, update records, view analytics, and recover from errors reliably.

24. Monitor and Maintain the Dashboard

After launch, monitor how the application behaves in real usage.

Track API response times, server errors, database connections, slow queries, background job failures, and frontend exceptions.

Add structured logs with request identifiers so developers can investigate issues without recording unnecessary personal information.

Monitor the health of reminder jobs and integrations. A dashboard may appear operational even when its scheduled notifications have silently stopped working.

Regularly review dependencies, access permissions, backups, and recovery procedures.

Gather feedback from sales representatives and managers. They may identify practical improvements, such as faster lead entry, clearer status labels, or better overdue-task visibility.

Use actual user behavior to prioritize improvements instead of adding features simply because they are technically interesting.

25. Common Mistakes to Avoid

Developers frequently encounter similar problems when building CRM-style applications.

Building too many features too early: Start with the core workflow and expand after the MVP is stable.

Using an unclear database structure: Define relationships, constraints, and ownership rules before implementing complex features.

Trusting the frontend for security: Enforce permissions and validation on the backend.

Loading every record at once: Use server-side filtering and pagination.

Calculating metrics inconsistently: Document reporting definitions and use consistent date boundaries.

Ignoring follow-up workflows: Make reminders and activity tracking part of the initial design if sales follow-ups are central to the business.

Skipping automated tests: Test critical workflows and access controls before deployment.

Ignoring backups and monitoring: Prepare for failures rather than assuming the application will always remain available.

Overcomplicating the architecture: Start with a well-organized modular application. Introduce microservices only when specific requirements justify their additional operational cost.

Avoiding these mistakes can save significant development time and reduce the risk of expensive problems after launch.

26. Suggested Development Roadmap

A phased roadmap makes the project easier to manage.

Phase 1: Planning and design

Define user roles, lead statuses, database relationships, wireframes, and API contracts.

Phase 2: Backend development

Create the database schema, authentication system, lead CRUD endpoints, filtering, pagination, and validation.

Phase 3: Frontend development

Build the navigation, dashboard layout, lead forms, data tables, filters, and API integration.

Phase 4: Sales workflows

Implement lead assignment, pipeline stages, activity tracking, and follow-up reminders.

Phase 5: Analytics

Add metric cards, source reports, conversion charts, and campaign attribution.

Phase 6: Security and testing

Test permissions, validate business rules, audit sensitive operations, and run automated tests.

Phase 7: Deployment and improvement

Deploy the application, configure monitoring and backups, gather feedback, and prioritize improvements.

The duration of each phase depends on the developer's experience, team size, integration requirements, and project scope.

Conclusion

Building a lead management dashboard from scratch is a valuable full-stack development project that combines practical business requirements with modern engineering techniques.

React provides an interactive frontend, FastAPI handles API requests and business logic, and PostgreSQL stores structured lead and activity data. Together, these technologies support a maintainable foundation for lead tracking, sales pipeline management, team collaboration, and marketing analytics.

The most important part of the project is not simply creating attractive charts or displaying numbers. It is building a reliable workflow that helps businesses capture prospects, assign responsibility, maintain consistent records, follow up at the right time, and measure results accurately.

Start with a small, secure, well-tested MVP. Focus on clear database relationships, consistent business rules, meaningful dashboard metrics, and a responsive user experience. Then introduce automation, advanced reporting, and external integrations as the business needs evolve.

For full-stack developers, this project demonstrates much more than the ability to write React components or create API endpoints. It shows an understanding of system architecture, data modeling, authentication, analytics, testing, deployment, and real-world business processes.

A well-designed lead management dashboard can become the foundation for a broader CRM platform and a strong portfolio project that demonstrates practical software development skills.

How to Build a Customer Management System with React and FastAPI

Wed, 14 Oct 2026 03:47:00 +0000

Customer relationships are one of the most important parts of running a successful business. Whether a company operates an e-commerce store, a digital marketing agency, a software development firm, or a consulting service, managing customer information efficiently can make a significant difference in productivity and customer satisfaction.

Many businesses begin by storing customer information in spreadsheets, documents, or disconnected applications. Although these methods may work for a small number of customers, they become increasingly difficult to maintain as a business grows. Duplicate records, missing information, delayed follow-ups, and limited reporting can eventually affect the entire customer management process.

A Customer Management System (CMS) provides a centralized place to organize customer information, track interactions, update contact details, and manage business relationships. When designed properly, it helps teams access accurate information, collaborate more effectively, and make better decisions.

In this article, we will explore how to build a customer management system using React for the frontend and FastAPI for the backend. We will discuss the architecture, database design, API development, authentication, CRUD operations, frontend integration, testing, deployment, and security considerations.

The goal is not simply to create an application that displays customer records. Instead, we will examine how to build a maintainable, secure, and scalable application using modern full-stack development practices.

1. Understanding the Customer Management System

Before writing code, we need to understand what our application should accomplish.

A customer management system stores customer information and provides tools for managing that information throughout the customer lifecycle.

For our example project, we will build a web application that allows authorized users to:

View a list of customers.
Add new customer records.
Update existing customer information.
Delete customer records when appropriate.
Search for customers by name or email.
Filter records by customer status.
View individual customer details.
Access the system through an authenticated account.

Additional features, such as activity histories, notes, sales opportunities, and reporting dashboards, can be added as the application evolves.

Why choose React and FastAPI?

React and FastAPI complement each other well because they solve different parts of the application.

React is a JavaScript library for building interactive user interfaces. It allows developers to create reusable components, manage application state, and update the interface when data changes.

FastAPI is a Python framework for developing APIs. It supports request validation, automatic API documentation, asynchronous programming, and type hints.

Together, these technologies provide a practical foundation for a modern customer management application.

React handles presentation and user interactions, while FastAPI handles business logic, validation, authorization, and communication with the database.

2. Planning the Application Architecture

A well-designed application separates responsibilities into distinct layers.

Our customer management system will use three primary components:

Frontend: React provides the user interface, including forms, tables, search fields, and customer detail views.

Backend: FastAPI exposes HTTP endpoints that receive requests, validate input, enforce business rules, and return responses.

Database: PostgreSQL stores customer records persistently and supports structured queries.

The application follows a typical client-server architecture.

When a user opens the customer list, React sends an HTTP request to FastAPI. The backend queries PostgreSQL, retrieves the relevant records, and returns them as JSON. React then renders the returned information in the interface.

When a user creates a customer, the frontend sends the form data to the backend. FastAPI validates the request, saves the record in the database, and returns the newly created customer.

This separation makes the application easier to test, maintain, and extend.

For example, we could later replace the React frontend with a mobile application without rewriting the core customer management logic, provided the API remains compatible.

3. Setting Up the Development Environment

Before building the application, install the required development tools:

Python 3.11 or a compatible modern Python version.
Node.js and npm.
PostgreSQL.
A code editor such as Visual Studio Code.
Git for version control.

Create a project directory with separate frontend and backend folders.

customer-management-system/
├── backend/
│   ├── app/
│   │   ├── main.py
│   │   ├── database.py
│   │   ├── models.py
│   │   ├── schemas.py
│   │   └── routers/
│   │       └── customers.py
│   ├── requirements.txt
│   └── .env
│
├── frontend/
│   ├── src/
│   │   ├── components/
│   │   ├── pages/
│   │   ├── services/
│   │   └── App.jsx
│   └── package.json
│
└── README.md

This structure is intentionally simple. As the application grows, we can introduce dedicated service layers, authentication modules, tests, and database migration files.

Creating the React application

Use Vite to initialize the frontend.

npm create vite@latest frontend -- --template react
cd frontend
npm install
npm run dev

Vite provides a fast development server and a straightforward production build process.

Creating the FastAPI backend

Create a Python virtual environment inside the backend directory.

cd backend
python -m venv venv

Activate the environment on Windows:

venv\Scripts\activate

On Linux or macOS, use:

source venv/bin/activate

Install the main backend dependencies.

pip install fastapi uvicorn sqlalchemy \
  psycopg[binary] pydantic-settings

SQLAlchemy will manage database interactions, while the PostgreSQL driver allows Python to connect to the database.

Record the installed dependencies in requirements.txt so other developers can reproduce the environment.

4. Designing the Customer Database

Database design is a critical step because customer information must remain consistent as the application grows.

For our initial version, a customer record will include:

Field	Purpose
id	Unique customer identifier
full_name	Customer's full name
email	Contact email address
phone	Optional phone number
company	Optional company name
status	Current customer status
created_at	Record creation timestamp

The id field serves as the primary key. Email addresses should generally be unique if the business considers one email address to represent one customer account.

The status field might contain values such as lead, active, or inactive. The exact categories should reflect the business's actual workflow.
In PostgreSQL, the conceptual table could look like this:

CREATE TABLE customers (
    id SERIAL PRIMARY KEY,
    full_name VARCHAR(150) NOT NULL,
    email VARCHAR(255) NOT NULL UNIQUE,
    phone VARCHAR(30),
    company VARCHAR(150),
    status VARCHAR(20) NOT NULL DEFAULT 'lead',
    created_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
);

This SQL example illustrates the table structure. In the application, we should use a database migration system, such as Alembic, to manage schema changes safely.

We should also consider indexes for frequently searched fields. A unique constraint on email already creates a suitable database index in PostgreSQL. Additional indexes should be introduced when query patterns and performance measurements justify them.

For a production application, consider storing customer interactions in separate tables rather than placing every activity into the customer record. This allows one customer to have many notes, calls, emails, or sales opportunities without creating an unnecessarily large table.

5. Connecting FastAPI to PostgreSQL

The backend needs a reliable database connection before it can retrieve or modify customer records.

Create a .env file containing the database connection string.

DATABASE_URL=postgresql+psycopg://user:password@localhost/customer_db

Replace the example credentials with your own development database details. Never commit real production credentials to Git.
Next, create database.py.

import os

from sqlalchemy import create_engine
from sqlalchemy.orm import DeclarativeBase, sessionmaker

DATABASE_URL = os.environ["DATABASE_URL"]

engine = create_engine(
    DATABASE_URL,
    pool_pre_ping=True,
)

SessionLocal = sessionmaker(
    bind=engine,
    autoflush=False,
    expire_on_commit=False,
)

class Base(DeclarativeBase):
    pass

For local development, you can load environment variables using a configuration library or a development environment loader. In production, prefer your hosting platform's secret management system.

We can provide a database session to FastAPI endpoints through a dependency.

from collections.abc import Generator

from sqlalchemy.orm import Session

from app.database import SessionLocal

def get_db() -> Generator[Session, None, None]:
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

This pattern ensures that each request receives a database session and that the session is closed afterward.

For synchronous SQLAlchemy sessions, use regular def endpoints rather than performing blocking database operations inside an async def endpoint. Alternatively, use SQLAlchemy's asynchronous engine and session APIs when an asynchronous database architecture is appropriate.

6. Creating the Customer Model

SQLAlchemy models describe how application objects map to database tables.

Create models.py.

from datetime import datetime

from sqlalchemy import (
    DateTime,
    String,
    func,
)
from sqlalchemy.orm import Mapped, mapped_column

from app.database import Base

class Customer(Base):
    __tablename__ = "customers"

    id: Mapped[int] = mapped_column(
        primary_key=True
    )

    full_name: Mapped[str] = mapped_column(
        String(150),
        nullable=False,
    )
    email: Mapped[str] = mapped_column(
        String(255),
        unique=True,
        index=True,
        nullable=False,
    )
    phone: Mapped[str | None] = mapped_column(
        String(30),
        nullable=True,
    )
    company: Mapped[str | None] = mapped_column(
        String(150),
        nullable=True,
    )
    status: Mapped[str] = mapped_column(
        String(20),
        default="lead",
        nullable=False,
    )
    created_at: Mapped[datetime] = mapped_column(
        DateTime(timezone=True),
        server_default=func.now(),
        nullable=False,
    )
The model establishes the relationship between Python objects and the customer table.

Notice that optional values use nullable fields, while required values are explicitly marked as non-nullable.

The database should enforce critical constraints independently of frontend validation. A malicious or incorrectly configured client must not be able to bypass important data integrity rules simply by sending a direct HTTP request.

In this example, `status` is a string. A production implementation should validate it against an explicit set of allowed values and may use a database enum or a check constraint for stronger consistency.

## 7. Defining Request and Response Schemas

Database models and API schemas serve different purposes.

A database model describes how data is stored. A Pydantic schema describes what the API accepts and returns.

Separating these responsibilities prevents clients from controlling internal fields such as database identifiers, timestamps, or administrative flags.

Create `schemas.py`.

```python
from datetime import datetime
from typing import Literal

from pydantic import BaseModel, ConfigDict, EmailStr, Field

CustomerStatus = Literal["lead", "active", "inactive"]

class CustomerCreate(BaseModel):
    full_name: str = Field(
        min_length=2,
        max_length=150,
    )
    email: EmailStr
    phone: str | None = Field(
        default=None,
        max_length=30,
    )
    company: str | None = Field(
        default=None,
        max_length=150,
    )
    status: CustomerStatus = "lead"

class CustomerUpdate(BaseModel):
    full_name: str | None = Field(
        default=None,
        min_length=2,
        max_length=150,
    )
    email: EmailStr | None = None
    phone: str | None = Field(
        default=None,
        max_length=30,
    )
    company: str | None = Field(
        default=None,
        max_length=150,
    )
    status: CustomerStatus | None = None

class CustomerResponse(BaseModel):
    model_config = ConfigDict(from_attributes=True)

    id: int
    full_name: str
    email: str
    phone: str | None
    company: str | None
    status: CustomerStatus
    created_at: datetime

Install the email validation dependency if needed:

pip install email-validator

Pydantic validates incoming values and helps FastAPI produce consistent API responses.

One important detail concerns partial updates. We will use model_dump(exclude_unset=True) so that fields omitted from a PATCH request remain unchanged. If the client explicitly sends null for an optional field, the backend can distinguish that from an omitted field.

We should also ensure that a missing or null full_name is rejected during a partial update rather than being written into a required database column.

8. Building the Customer API

Now we can create the endpoints that power the application.

A practical API design might include:

Method	Endpoint	Purpose
GET	`/api/customers`	List customers
GET	`/api/customers/{id}`	Retrieve one customer
POST	`/api/customers`	Create a customer
PATCH	`/api/customers/{id}`	Update selected fields
DELETE	`/api/customers/{id}`	Delete a customer

These endpoints follow common REST conventions.

Listing customers

Create routers/customers.py.

from fastapi import APIRouter, Depends, HTTPException, Query
from sqlalchemy import select
from sqlalchemy.orm import Session

from app.database import get_db
from app.models import Customer
from app.schemas import (
    CustomerCreate,
    CustomerResponse,
    CustomerUpdate,
)
router = APIRouter(
    prefix="/api/customers",
    tags=["Customers"],
)
@router.get("/", response_model=list[CustomerResponse])
def list_customers(
    q: str | None = None,
    limit: int = Query(default=20, ge=1, le=100),
    offset: int = Query(default=0, ge=0),
    db: Session = Depends(get_db),
):
    statement = select(Customer)

    if q:
        statement = statement.where(
            Customer.full_name.ilike(f"%{q}%")
            | Customer.email.ilike(f"%{q}%")
        )

    statement = (
        statement
        .order_by(Customer.id.desc())
        .limit(limit)
        .offset(offset)
    )

    return db.scalars(statement).all()
This endpoint retrieves customers with pagination and a simple search option.

The `limit` and `offset` parameters prevent the backend from returning an unlimited number of records in a single request.

For larger datasets, consider full-text search or a dedicated search service. Also, escape SQL `LIKE` wildcard characters if the application needs literal substring-search behavior. SQLAlchemy parameterizes values, protecting against ordinary SQL injection, but wildcard characters still have search semantics.

A further improvement would return pagination metadata, including the total record count and the next page token or offset.

### Retrieving a single customer

```python
@router.get("/{customer_id}", response_model=CustomerResponse)
def get_customer(
    customer_id: int,
    db: Session = Depends(get_db),
):
    customer = db.get(Customer, customer_id)

    if customer is None:
        raise HTTPException(
            status_code=404,
            detail="Customer not found",
        )

    return customer
The endpoint returns a clear `404 Not Found` response when the requested customer does not exist.

### Creating a customer

```python
@router.post(
    "/",
    response_model=CustomerResponse,
    status_code=201,
)
def create_customer(
    payload: CustomerCreate,
    db: Session = Depends(get_db),
):
    existing = db.scalar(
        select(Customer).where(
            Customer.email == str(payload.email)
        )
    )

    if existing:
        raise HTTPException(
            status_code=409,
            detail="A customer with this email already exists",
        )

    customer = Customer(
        **payload.model_dump()
    )

    db.add(customer)

    try:
        db.commit()
        db.refresh(customer)
    except Exception:
        db.rollback()
        raise

    return customer
The endpoint validates the incoming payload, checks for an existing email, saves the new customer, and returns the stored record.

The database's unique constraint remains essential because two simultaneous requests could pass the initial duplicate check. A robust production implementation should handle the resulting database integrity violation and return a consistent conflict response rather than exposing a raw database error.

Email normalization should also be considered. For example, an application may choose to trim surrounding whitespace and normalize email addresses consistently before storage.

### Updating customer information

```python
@router.patch(
    "/{customer_id}",
    response_model=CustomerResponse,
)
def update_customer(
    customer_id: int,
    payload: CustomerUpdate,
    db: Session = Depends(get_db),
):
    customer = db.get(Customer, customer_id)

    if customer is None:
        raise HTTPException(
            status_code=404,
            detail="Customer not found",
        )

    changes = payload.model_dump(exclude_unset=True)

    if changes.get("full_name") is None:
        if "full_name" in changes:
            raise HTTPException(
                status_code=422,
                detail="Full name cannot be null",
            )

    if "email" in changes and changes["email"] is not None:
        duplicate = db.scalar(
            select(Customer).where(
                Customer.email == str(changes["email"]),
                Customer.id != customer_id,
            )
        )

        if duplicate:
            raise HTTPException(
                status_code=409,
                detail="Email is already assigned to another customer",
            )

        changes["email"] = str(changes["email"])

    for field, value in changes.items():
        setattr(customer, field, value)

    try:
        db.commit()
        db.refresh(customer)
    except Exception:
        db.rollback()
        raise

    return customer
This endpoint updates only the fields included in the request.

In a production codebase, the database integrity error handling should be more specific, and the backend should reject explicit null values for all required fields. We should also define whether an empty update request is valid.

### Deleting a customer

```python
@router.delete("/{customer_id}", status_code=204)
def delete_customer(
    customer_id: int,
    db: Session = Depends(get_db),
):
    customer = db.get(Customer, customer_id)

    if customer is None:
        raise HTTPException(
            status_code=404,
            detail="Customer not found",
        )

    db.delete(customer)
    db.commit()
    return None

For business applications, permanent deletion is not always the best choice. Soft deletion or archival may be preferable when the business needs an audit trail or must preserve historical transactions.

Deletion rules should also account for related records and applicable privacy requirements.

9. Registering the API Router

Create main.py to initialize the FastAPI application.

from fastapi import FastAPI
from fastapi.middleware.cors import CORSMiddleware

from app.routers.customers import router as customers_router

app = FastAPI(
    title="Customer Management API",
    version="1.0.0",
)

app.add_middleware(
    CORSMiddleware,
    allow_origins=["http://localhost:5173"],
    allow_credentials=False,
    allow_methods=["GET", "POST", "PATCH", "DELETE"],
    allow_headers=["Content-Type", "Authorization"],
)

app.include_router(customers_router)

@app.get("/health")
def health_check():
    return {"status": "ok"}
The CORS configuration allows the local React development server to communicate with the backend.

In production, configure the actual frontend origin rather than allowing every website to make cross-origin requests. CORS is a browser security mechanism, not a substitute for authentication or authorization.

Start the development server:

```bash
uvicorn app.main:app --reload
``
Visit `http://localhost:8000/docs` to explore FastAPI's interactive API documentation.

Before running the application, ensure the database schema has been created through migrations. The model definitions alone do not automatically create the tables in this setup.

## 10. Connecting React to the Backend

The frontend should communicate with FastAPI through a dedicated service module rather than scattering request logic across every component.

Create `src/services/customerService.js`.

```javascript
const API_BASE_URL =
  import.meta.env.VITE_API_BASE_URL ||
  "http://localhost:8000";

export async function getCustomers(query = "") {
  const params = new URLSearchParams({
    limit: "20",
    offset: "0",
  });

  if (query.trim()) {
    params.set("q", query.trim());
  }

  const response = await fetch(
    `${API_BASE_URL}/api/customers/?${params}`
  );

  if (!response.ok) {
    throw new Error("Failed to load customers");
  }

  return response.json();
}

export async function createCustomer(customer) {
  const response = await fetch(
    `${API_BASE_URL}/api/customers/`,
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
      },
      body: JSON.stringify(customer),
    }
  );

  if (!response.ok) {
    const error = await response.json();
    throw new Error(
      error.detail || "Failed to create customer"
    );
  }

  return response.json();
}

The service module centralizes API communication and error handling.

For a larger application, add functions for retrieving a single customer, updating records, deleting customers, and handling authentication.

The API base URL should be configurable through environment variables. Remember that frontend environment variables are generally included in the built application, so they must never contain secrets.

11. Building the Customer List Component

React components turn API data into an interactive interface.

Create a basic customer list in src/components/CustomerList.jsx.

import { useEffect, useState } from "react";
import { getCustomers } from "../services/customerService";

export default function CustomerList() {
  const [customers, setCustomers] = useState([]);
  const [query, setQuery] = useState("");
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState("");

  useEffect(() => {
    let cancelled = false;

    async function loadCustomers() {
      setLoading(true);
      setError("");

      try {
        const data = await getCustomers(query);

        if (!cancelled) {
          setCustomers(data);
        }
      } catch {
        if (!cancelled) {
          setError("Unable to load customer records.");
        }
      } finally {
        if (!cancelled) {
          setLoading(false);
        }
      }
    }

    loadCustomers();

    return () => {
      cancelled = true;
    };
  }, [query]);

  if (loading) {
    return <p>Loading customers...</p>;
  }

  return (
    <section>
      <h1>Customers</h1>

      <input
        value={query}
        onChange={(event) => setQuery(event.target.value)}
        placeholder="Search customers"
        aria-label="Search customers"
      />

      {error && <p role="alert">{error}</p>}

      {!error && customers.length === 0 && (
        <p>No customers found.</p>
      )}

      <ul>
        {customers.map((customer) => (
          <li key={customer.id}>
            <strong>{customer.full_name}</strong>
            <span> — {customer.email}</span>
            <span> ({customer.status})</span>
          </li>
        ))}
      </ul>
    </section>
  );
}

This component demonstrates several essential React concepts.

The useState hook stores the customer list, search query, loading status, and error message. The useEffect hook fetches data when the query changes. The map method renders each customer using a stable key.

The cancellation flag prevents a completed request from updating state after the effect has been cleaned up. In a larger application, AbortController can cancel obsolete requests, especially when users type quickly into the search field.

For production search, add a debounce delay to avoid sending a new request for every keystroke. You should also handle HTTP errors, network failures, and authentication expiration consistently.

12. Creating a Customer Form

A customer management application needs a form for creating and updating records.

A simple form can use controlled React inputs, meaning React state holds the current field values.

import { useState } from "react";
import { createCustomer } from "../services/customerService";

const initialForm = {
  full_name: "",
  email: "",
  phone: "",
  company: "",
  status: "lead",
};

export default function CustomerForm({ onCreated }) {
  const [form, setForm] = useState(initialForm);
  const [error, setError] = useState("");
  const [saving, setSaving] = useState(false);

  function updateField(event) {
    const { name, value } = event.target;

    setForm((current) => ({
      ...current,
      [name]: value,
    }));
  }

  async function handleSubmit(event) {
    event.preventDefault();
    setError("");
    setSaving(true);

    try {
      const customer = await createCustomer({
        ...form,
        phone: form.phone || null,
        company: form.company || null,
      });

      setForm(initialForm);
      onCreated?.(customer);
    } catch (err) {
      setError(err.message || "Unable to save customer.");
    } finally {
      setSaving(false);
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      <h2>Add Customer</h2>

      <label>
        Full name
        <input
          name="full_name"
          value={form.full_name}
          onChange={updateField}
          required
          minLength={2}
          maxLength={150}
        />
      </label>

      <label>
        Email
        <input
          type="email"
          name="email"
          value={form.email}
          onChange={updateField}
          required
        />
      </label>

      <label>
        Phone
        <input
          name="phone"
          value={form.phone}
          onChange={updateField}
        />
      </label>

      <label>
        Company
        <input
          name="company"
          value={form.company}
          onChange={updateField}
        />
      </label>

      <label>
        Status
        <select
          name="status"
          value={form.status}
          onChange={updateField}
        >
          <option value="lead">Lead</option>
          <option value="active">Active</option>
          <option value="inactive">Inactive</option>
        </select>
      </label>

      {error && <p role="alert">{error}</p>}

      <button type="submit" disabled={saving}>
        {saving ? "Saving..." : "Save Customer"}
      </button>
    </form>
  );
}

The form uses native HTML validation for a better user experience, but frontend validation is not sufficient on its own. FastAPI and Pydantic must continue to validate every incoming request.

The onCreated callback allows a parent component to refresh the customer list after a successful submission.

For editing, reuse the form with initial values loaded from an existing customer. Make sure the application distinguishes between creating a new record and updating an existing one.

13. Organizing the Dashboard

A useful customer management dashboard should make important information easy to understand.

Consider organizing the interface into the following sections:

Navigation sidebar: Links to Dashboard, Customers, Activities, Reports, and Settings.

Summary cards: Display the total number of customers, active customers, new leads, and inactive records.

Customer table: Show names, email addresses, companies, statuses, and available actions.

Search and filters: Help users locate records quickly.

Customer detail page: Display contact information and a history of interactions.

Create and edit dialogs: Provide a focused interface for changing customer information.

React supports this structure through reusable components. For example, a StatCard component can display different metrics, while a CustomerTable component handles the presentation of customer records.

A consistent design system helps avoid duplicated styling and makes future improvements easier.

Accessibility should be part of the interface from the beginning. Use meaningful labels, visible focus indicators, sufficient color contrast, keyboard-accessible controls, and clear validation messages. Do not rely on color alone to communicate a customer's status.

14. Implementing Search, Filtering, and Pagination

Search becomes increasingly important when a business manages hundreds or thousands of customers.

The backend can accept query parameters such as:

/api/customers/?q=alex&limit=20&offset=0

The search term can match a customer's name or email address.

Filtering by status can be added through another parameter:

/api/customers/?status=active&limit=20&offset=0
``
The backend should validate the status value and apply it to the database query.

Pagination allows the application to load records in manageable batches. Without pagination, a large response may increase database load, network transfer, and rendering time.
For a straightforward administrative application, limit-and-offset pagination is often sufficient. For very large or rapidly changing datasets, cursor-based pagination may offer more predictable performance.

Search and filtering should be performed on the backend when the dataset is large. Filtering only the currently loaded React array may incorrectly suggest that no matching records exist elsewhere in the database.

## 15. Adding Authentication and Authorization

A customer management system often contains personal information, so authentication and authorization must be designed carefully.

Authentication determines who the user is. Authorization determines what that user is allowed to do.

A practical production implementation should include:

- User registration or administrator-created accounts.
- Secure login and logout.
- Password hashing with a modern password-hashing algorithm.
- Access control for customer endpoints.
- Role-based permissions where required.
- Session expiration and revocation.
- Audit logging for sensitive changes.

FastAPI supports security dependencies and OAuth2-compatible authentication flows. Depending on the application, you may use short-lived access tokens, refresh-token rotation, or secure server-managed sessions.

If browser cookies are used for authentication, configure `HttpOnly`, `Secure`, and appropriate `SameSite` attributes, and implement appropriate CSRF protection for state-changing requests.

If bearer tokens are used, protect token storage and transmission. Avoid storing long-lived sensitive tokens in browser-accessible storage without carefully considering the risks.

Most importantly, every protected endpoint must enforce authorization on the server. Hiding a Delete button in React does not prevent an unauthorized user from calling the delete endpoint directly.

For a multi-company application, every customer query must also be scoped to the authenticated user's organization. Guessing another customer's numeric ID must never grant access to that record.

## 16. Securing Customer Data

Security should be treated as an ongoing engineering responsibility rather than a final checklist.

First, use HTTPS in production to protect data in transit.

Second, keep database credentials, signing keys, and other secrets outside source control.

Third, validate and normalize incoming data before storing it. Use parameterized database operations and avoid building SQL statements through string concatenation.

Fourth, apply the principle of least privilege. The application's database account should have only the permissions required for normal operations.

Fifth, limit the information returned by API endpoints. Internal notes, private account details, and administrative fields should not be exposed unless the requesting user has permission to access them.

Sixth, implement rate limiting and appropriate request-size limits to reduce abuse.

Seventh, maintain backups and periodically test the recovery process.

Finally, establish data retention and deletion policies that fit the business's legal and operational requirements. Logging should avoid exposing passwords, access tokens, or unnecessary personal information.

A secure application combines technical controls, appropriate operational procedures, and clear rules about who can access customer information.

## 17. Testing the Application

Testing helps ensure that customer records remain reliable as the code changes.

### Backend testing

Use `pytest` and FastAPI's `TestClient` to test API behavior.

Important test cases include:

- Creating a customer with valid data.
- Rejecting an invalid email address.
- Rejecting a duplicate email address.
- Returning a `404` response for a missing customer.
- Updating one field without changing others.
- Rejecting an invalid customer status.
- Preventing unauthorized access.
- Preventing users from accessing another organization's records.

Use a dedicated test database rather than running destructive tests against production data.

### Frontend testing

Use a React testing library to verify user interactions.

For example, test that the customer form displays validation feedback, disables the submit button while saving, and shows the newly created customer after a successful response.

Also test loading states, empty search results, server errors, and network failures.

End-to-end tests can verify the complete workflow, from logging in and creating a customer to editing the record and confirming that the change persists.

Automated tests should be integrated into a continuous integration pipeline so that regressions are detected before deployment.

## 18. Improving Performance and Scalability

An application that works well with twenty customers may struggle with fifty thousand. Performance decisions should be guided by measurements and expected usage.

Start with database indexes for common filters and sorting operations. Use query plans to identify expensive database operations instead of adding indexes without evidence.

Keep API responses focused. Return only the fields the frontend needs, and use pagination to control response sizes.

Avoid repeatedly fetching the same data when a safe caching strategy would work. However, cached customer information must respect authorization boundaries and must be invalidated when necessary.

React performance improvements may include component memoization, virtualization for very large lists, and reducing unnecessary state updates. These techniques should be introduced when profiling shows they are useful.

If the application needs to process large imports, send notifications, or generate complex reports, consider background workers and a task queue rather than making every HTTP request wait for a long-running job.

For multi-tenant systems, tenant isolation should be built into database access patterns and tested thoroughly.

As usage increases, monitor request latency, database connection utilization, error rates, and resource consumption. Good observability makes it easier to identify the actual cause of performance problems.

## 19. Deploying the Application

Deployment turns the development project into a service that real users can access.

A typical production environment includes:

- A hosting platform for the React frontend.
- A hosting platform or container environment for FastAPI.
- A managed PostgreSQL database.
- HTTPS and correctly configured DNS.
- Environment-based configuration.
- Automated backups and monitoring.

Build the React application for production:

```bash
npm run build
``
## 20. Future Features Worth Adding

Once the basic system is reliable, several features can make it more useful for real business operations.

**Customer activity timeline:** Record calls, emails, meetings, and important interactions.

**Notes and reminders:** Help staff remember follow-ups and customer requirements.

**Import and export:** Support controlled CSV imports and exports, including duplicate detection and validation reports.

**Advanced reporting:** Track new leads, customer retention, status changes, and team activity.

**Email integration:** Connect customer records to relevant email conversations, with appropriate permissions.

**Team collaboration:** Assign customers to staff members and track ownership changes.

**Audit trail:** Record who changed important fields and when.

**CRM integration:** Synchronize records with other business systems through documented APIs.

Avoid adding features simply because they sound impressive. Prioritize those that solve genuine problems for the intended users.

## 21. Common Mistakes to Avoid

Several mistakes can make a customer management system difficult to maintain.

**Mixing frontend and backend responsibilities:** React should not connect directly to the production database. Database access belongs in the backend.

**Ignoring validation:** Validate incoming data at the API boundary and enforce important constraints in the database.

**Returning every customer in one response:** Large datasets need pagination and carefully designed queries.

**Skipping authentication:** A public customer endpoint is inappropriate for private business information.

**Ignoring authorization:** A logged-in user should not automatically have permission to access every record.

**Handling errors inconsistently:** Use clear HTTP status codes and structured error responses.

**Hardcoding configuration:** Use environment-specific configuration instead of committing secrets or production URLs into application code.

**Skipping automated tests:** Basic tests can catch duplicate handling, data corruption, and permission regressions early.

**Overcomplicating the architecture:** Start with a clear modular design. Introduce additional services and infrastructure when the project's requirements justify them.

Avoiding these mistakes early will save time and reduce the cost of future maintenance.

For developers building a portfolio project, this application is also a valuable opportunity to demonstrate practical engineering skills. A well-documented repository, automated tests, a working deployment, and a clear explanation of architectural decisions can show potential employers or clients that you understand how to build more than a simple user interface.

With careful planning and iterative development, React and FastAPI can provide a strong foundation for a maintainable customer management application that grows alongside the business.

Building a Smarter useIdle Hook in React: Solving the Short-Timeout Edge Case

Wed, 07 Oct 2026 09:35:26 +0000

Tracking user inactivity in web applications seems straightforward at first. You listen to a few mouse and keyboard events, set a timeout, and toggle state when the timer expires. However, once you start optimizing for performance, things get tricky.

To prevent your app from grinding to a halt during heavy mouse movement, you must throttle the event handlers. But what happens if a developer configures a very short idle timeout—say, for a rapid UI transition or testing? If your throttle interval is static, it can easily clash with the timeout length, causing missed events or inconsistent state transitions.

In the latest release of react-hook-lab, we solved this exact problem by introducing dynamic adaptive throttling to our useIdle hook.

The Problem with Fixed Throttling

Previously, useIdle utilized a fixed throttle duration. If the user moved their mouse rapidly, events were ignored for a set period to save CPU cycles. However, if a developer set a short timeout duration close to or lower than the throttle limit, the hook could miss the final active event and incorrectly report the user as idle.

Furthermore, initializing the tracking state at 0 instead of backdating it meant the hook could experience a sluggish response immediately after mounting.

The Solution: Dynamic Adaptation

To resolve this, we modified useIdle to dynamically compute an effectiveThrottle. It now ensures the throttle interval is never larger than half of the requested timeout duration:

const effectiveThrottle = Math.min(THROTTLE_MS, Math.floor(timeout / 2));

Additionally, we corrected the initial state of the active tracking reference. By setting it to -THROTTLE_MS on mount, the very first user interaction triggers an immediate, unthrottled update.

Practical Code Examples

Here are two ways you can leverage the newly optimized useIdle hook in your React applications.

Example 1: Protecting Secure Sessions (Standard Timeout)

For security-sensitive interfaces, you want to warn users before their session expires. With a standard timeout, useIdle works efficiently in the background without causing unnecessary re-renders during active scrolling or typing.

import React from "react";
import { useIdle } from "react-hook-lab";

export function SessionTimeoutWarning() {
  // Trigger idle warning after 5 minutes of inactivity
  const isIdle = useIdle(300000);

  return (
    <div className="session-banner">
      {isIdle ? (
        <div className="warning">
          <p>You have been inactive for 5 minutes. Your session will lock soon.</p>
          <button onClick={() => window.location.reload()}>Extend Session</button>
        </div>
      ) : (
        <p className="status">Secure connection active.</p>
      )}
    </div>
  );
}

Example 2: Interactive Video Player HUD (Short Timeout)

When building a video streaming client, you want to hide the playback controls (HUD) quickly when the user stops moving their cursor. This requires a very short timeout of 2 seconds. Thanks to our dynamic adaptive throttling, this short window no longer glitches out.

import React from "react";
import { useIdle } from "react-hook-lab";

export function VideoPlayerHUD() {
  // Hide controls after 2 seconds of inactivity
  const isControlsIdle = useIdle(2000);

  return (
    <div className="video-container" style={{ position: "relative" }}>
      <video src="movie.mp4" width="100%" controls={false} />
      
      <div 
        className="controls-overlay"
        style={{
          opacity: isControlsIdle ? 0 : 1,
          transition: "opacity 0.3s ease-in-out"
        }}
      >
        <button>Play</button>
        <button>Pause</button>
        <span>01:23 / 05:40</span>
      </div>
    </div>
  );
}

Resources

GitHub Repository: react-hook-lab
NPM Package: react-hook-lab on npm
Connect on LinkedIn: Saurav Pandey

Originally published on my blog. You can read the alternative breakdown here.

From React to PostgreSQL: Understanding the Full Stack

Wed, 07 Oct 2026 05:22:39 +0000

Modern web applications are no longer built with a single technology. A production application usually involves multiple layers working together: a frontend that users interact with, a backend that processes requests, APIs that connect different components, and a database that stores information.

One of the most popular combinations for building modern full stack applications is React Node.js/Express + PostgreSQL. React provides an interactive user interface, the backend handles business logic and communication, and PostgreSQL provides reliable and structured data storage.

Understanding how these technologies communicate is much more valuable than simply learning each technology separately. A developer who understands the entire request lifecycle can build applications that are easier to maintain, debug, secure, and scale.

This article explores the complete journey from React in the browser to PostgreSQL in the database and explains how all the pieces fit together.

1. What Does "Full Stack" Actually Mean?

The term full stack development refers to working across multiple layers of a web application.

A typical application can be divided into four major areas:

**Frontend What users see and interact with
**Backend Server-side logic and application processing
**API Communication between frontend and backend
**Database Persistent storage of application data

A simplified architecture looks like this:

User
  ↓
React Frontend
  ↓
HTTP Request
  ↓
Backend / API
  ↓
Business Logic
  ↓
PostgreSQL Database
  ↓
Backend Response
  ↓
React UI Update

For example, imagine a task management application.

A user opens the application and sees a list of tasks. When they click "Add Task", React collects the task information and sends it to the backend.

The backend validates the information, processes the request, and sends an SQL query to PostgreSQL.

PostgreSQL stores the task and returns the result.

The backend then sends a response to React, and React updates the interface.

The entire process may happen in milliseconds.

Understanding this complete flow is the foundation of full-stack development.

2. React: The Frontend Layer

React is a JavaScript library for building user interfaces.

Instead of creating one large HTML page, React allows developers to divide an application into reusable components.

For example:

function TaskCard({ task }) {
  return (
    <div>
      <h3>{task.title}</h3>
      <p>{task.description}</p>
    </div>
  );
}

A larger application might contain components such as:

App
├── Navbar
├── Sidebar
├── Dashboard
├── TaskList
│   └── TaskCard
└── Footer

This component-based architecture makes large applications easier to manage.

React State

React applications frequently need to manage changing information.

For example:

const [tasks, setTasks] = useState([]);

The tasks variable contains the current data, while setTasks() updates it.

When the state changes, React re-renders the relevant part of the interface.

This makes React particularly useful for interactive applications.

Fetching Backend Data

React usually communicates with a backend through HTTP requests.

For example:

fetch("https://example.com/api/tasks")
  .then(response => response.json())
  .then(data => setTasks(data));

Modern applications may also use libraries such as Axios or tools provided by frameworks.

The important concept is that React itself normally does not communicate directly with PostgreSQL.

Instead, it communicates with the backend.

That separation is extremely important.

3. Why React Should Not Connect Directly to PostgreSQL

A beginner might wonder:

"If React can make network requests, why not connect React directly to PostgreSQL?"

The answer is security and architecture.

A browser application runs on the user's device. If database credentials were placed inside React code, anyone could potentially inspect them.

For example, exposing something like this would be extremely dangerous:

const databasePassword = "my-secret-password";

Frontend code is not a secure location for database credentials.

Instead, the architecture should look like:

React
   ↓
Backend API
   ↓
PostgreSQL

The backend protects the database credentials and controls what users are allowed to access.

This also allows the backend to perform validation, authentication, authorization, business logic, and database operations.

4. The Backend: Where the Application Thinks

The backend is responsible for processing requests from the frontend.

A popular JavaScript backend combination is:

Node.js
Express.js
PostgreSQL

Node.js allows JavaScript to run outside the browser.

Express provides tools for building APIs and handling HTTP requests.

A simple Express route might look like this:

app.get("/api/tasks", async (req, res) => {
  const result = await db.query("SELECT * FROM tasks");

  res.json(result.rows);
});

When React requests:

GET /api/tasks

the backend receives the request.

It queries PostgreSQL and returns the database results as JSON.

5. Understanding APIs

An API acts as a communication layer between different parts of an application.

For a task application, we might have:

GET    /api/tasks
GET    /api/tasks/:id
POST   /api/tasks
PUT    /api/tasks/:id
DELETE /api/tasks/:id

These endpoints represent different operations.

GET

Used to retrieve information.

GET /api/tasks

POST

Used to create new information.

POST /api/tasks

PUT or PATCH

Used to update information.

PATCH /api/tasks/25

DELETE

Used to remove information.

DELETE /api/tasks/25

This pattern is commonly associated with REST APIs.

A well-designed API gives the frontend a predictable way to communicate with the backend.

6. PostgreSQL: The Data Layer

PostgreSQL is a powerful open-source relational database system.

It stores information in tables containing rows and columns.

For example, a tasks table could look like:

tasks
------------------------------------------------
id | title          | completed | created_at
------------------------------------------------
1  | Learn React    | false     | ...
2  | Build API      | true      | ...
3  | Learn PostgreSQL| false    | ...

Each row represents a record.

Each column represents a property of that record.

A PostgreSQL table might be created using:

CREATE TABLE tasks (
    id SERIAL PRIMARY KEY,
    title VARCHAR(255) NOT NULL,
    description TEXT,
    completed BOOLEAN DEFAULT FALSE,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

PostgreSQL provides powerful features for data integrity, relationships, transactions, indexing, querying, and more.

7. SQL: How the Backend Talks to PostgreSQL

SQL stands for Structured Query Language.

Backend applications use SQL to interact with relational databases.

For example:

SELECT * FROM tasks;

returns tasks.

To create a task:

INSERT INTO tasks (title, description)
VALUES ('Learn Full Stack Development', 'Study React, APIs and PostgreSQL');

To update a task:

UPDATE tasks
SET completed = TRUE
WHERE id = 1;

To delete a task:

DELETE FROM tasks
WHERE id = 1;

These operations are the foundation of database-driven applications.

8. The Complete Request Lifecycle

Let's follow a real request from React to PostgreSQL.

Imagine a user submits this form:

Title: Learn PostgreSQL
Description: Understand relational databases

Step 1: React Collects the Data

React stores the form values in state.

const [title, setTitle] = useState("");
const [description, setDescription] = useState("");

When the user submits the form, React creates an HTTP request.

Step 2: React Sends the Request

fetch("/api/tasks", {
  method: "POST",
  headers: {
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    title,
    description
  })
});

The browser sends the request to the backend.

Step 3: Express Receives It

The backend route receives the request:

app.post("/api/tasks", async (req, res) => {
  const { title, description } = req.body;

  // validation and database logic
});

Step 4: Backend Validates the Data

The backend should never blindly trust frontend input.

It might check:

if (!title) {
  return res.status(400).json({
    error: "Title is required"
  });
}

Step 5: Backend Queries PostgreSQL

The server sends an SQL query:

INSERT INTO tasks (title, description)
VALUES ($1, $2)
RETURNING *;

The $1 and $2 parameters are supplied separately.

This is important because parameterized queries help protect against SQL injection.

Step 6: PostgreSQL Processes the Query

PostgreSQL validates the query, modifies the appropriate table, and returns the result.

Step 7: Backend Sends a Response

The backend may return:

{
  "id": 15,
  "title": "Learn PostgreSQL",
  "description": "Understand relational databases",
  "completed": false
}

Step 8: React Updates the UI

React receives the response and updates its state.

The new task then appears on the screen.

This is the complete full-stack cycle.

9. Authentication: Connecting Users to Data

Most real applications need authentication.

Users might register with:

Name
Email
Password

The backend stores account information in PostgreSQL.

Passwords should never be stored as plain text.

Instead, applications typically use secure password hashing algorithms such as bcrypt or Argon2.

After login, the application can issue an authentication token or session.

A common architecture looks like:

User
 ↓
React Login Form
 ↓
POST /api/login
 ↓
Backend
 ↓
Verify Password
 ↓
PostgreSQL
 ↓
Create Session/Token
 ↓
React

For protected requests, the frontend sends authentication information with the request.

The backend verifies it before allowing access to protected resources.

10. Database Relationships

Real-world applications rarely have only one table.

For example, a project management application might contain:

users
projects
tasks
comments

A user can have many projects.

A project can have many tasks.

A task can have many comments.

This creates relationships between tables.

For example:

CREATE TABLE users (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100),
    email VARCHAR(255) UNIQUE NOT NULL
);

Projects can reference users:

CREATE TABLE projects (
    id SERIAL PRIMARY KEY,
    name VARCHAR(255) NOT NULL,
    user_id INTEGER REFERENCES users(id)
);

The user_id creates a relationship between the project and its owner.

This is one of the most important concepts when moving from simple applications to production systems.

11. JOIN Queries

Relationships become powerful when combined with SQL joins.

For example:

SELECT
    projects.name,
    users.name AS owner
FROM projects
JOIN users
ON projects.user_id = users.id;

This can return:

Project             Owner
--------------------------------
Marketing Website   John
Mobile Application  Sarah
CRM Dashboard       David

Instead of storing everything in one giant table, relational databases allow information to be organized into connected structures.

This improves data consistency and maintainability.

12. Validation Must Happen on the Backend

Frontend validation is useful for user experience.

For example, React can tell a user:

Email is required.

But frontend validation alone is not enough.

A malicious user can bypass the React interface and send requests directly to the API.

Therefore, the backend must validate requests independently.

For example:

if (!email || !email.includes("@")) {
  return res.status(400).json({
    error: "Invalid email"
  });
}

Production applications often use validation libraries to create structured schemas.

The rule is simple:

Never trust client-side input.

13. Error Handling

Full-stack applications must also handle errors gracefully.

A database connection might fail.

A user might request a resource that doesn't exist.

A SQL query might fail.

A server might experience an unexpected error.

Instead of exposing internal errors to users, the backend should return appropriate HTTP status codes.

For example:

200 OK
201 Created
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
500 Internal Server Error

React can then display an appropriate message.

For example:

if (!response.ok) {
  setError("Unable to load tasks.");
}

Good error handling improves both user experience and debugging.

14. Environment Variables

Database credentials should not be hard-coded into application source code.

Instead, applications commonly use environment variables.

For example:

DATABASE_URL=postgresql://user:password@localhost:5432/myapp

The backend reads the value from the environment.

This allows different configurations for:

Development
Testing
Staging
Production

It also helps prevent sensitive credentials from being accidentally committed to Git repositories.

A .env file should generally be excluded from version control when it contains secrets.

15. ORM vs Raw SQL

Developers can communicate with PostgreSQL using raw SQL or an Object-Relational Mapping tool.

Raw SQL:

SELECT * FROM users WHERE id = $1;

ORMs provide a higher-level programming interface.

Popular choices in the JavaScript ecosystem include tools such as Prisma, Drizzle, and Sequelize.

An ORM can make common database operations easier to organize.

However, understanding SQL remains important.

Using an ORM without understanding databases can create problems when queries become complex or performance issues appear.

A strong full-stack developer should understand both the abstraction and the underlying database.

16. Database Indexing

As an application grows, database performance becomes increasingly important.

Suppose a users table contains millions of records.

A query like:

SELECT *
FROM users
WHERE email = '*Emails are not allowed*';

could become expensive without appropriate indexing.

An index can improve lookup performance:

CREATE INDEX idx_users_email
ON users(email);

Indexes are powerful, but they also have a cost.

They consume storage and can increase the cost of insert and update operations.

Therefore, indexes should be designed around actual query patterns.

17. Transactions

Some operations require multiple database changes to succeed together.

Imagine transferring money between two accounts.

You might need to:

Subtract money from Account A
Add money to Account B

If the first operation succeeds but the second fails, the database could become inconsistent.

Transactions solve this problem.

Conceptually:

BEGIN;

UPDATE accounts
SET balance = balance - 100
WHERE id = 1;

UPDATE accounts
SET balance = balance + 100
WHERE id = 2;

COMMIT;

If something goes wrong, the transaction can be rolled back.

Transactions are an important part of reliable backend systems.

18. Performance Across the Full Stack

Full-stack performance isn't just about writing fast React components.

Every layer can introduce delays.

Consider:

React rendering
       ↓
Network request
       ↓
Backend processing
       ↓
Database query
       ↓
Network response
       ↓
React rendering

If the database query takes 2 seconds, optimizing React alone won't solve the problem.

Similarly, if the API returns a massive JSON response, the frontend may still feel slow.

Performance should therefore be considered across the entire architecture.

Possible optimizations include:

React code splitting
Caching
API pagination
Database indexing
Efficient SQL queries
Connection pooling
Compression
CDN usage
Lazy loading
Server-side caching

19. Pagination

Imagine an application has 100,000 products.

Returning every product to React at once would be inefficient.

Instead, the API can use pagination.

For example:

GET /api/products?page=1&limit=20

The backend retrieves only the required records.

SQL might use:

SELECT *
FROM products
ORDER BY id
LIMIT 20 OFFSET 0;

Pagination reduces network traffic and improves application responsiveness.

For very large datasets, cursor-based pagination can provide better performance than large offsets.

20. Caching

Not every request needs to hit PostgreSQL.

Suppose thousands of users request the same popular product.

Repeatedly querying the database can create unnecessary load.

Caching can store frequently requested information temporarily.

The architecture might become:

React
 ↓
API
 ↓
Cache
 ↓
PostgreSQL

If the data exists in the cache, the backend can return it immediately.

Caching strategies need careful consideration because stale data can create incorrect results.

21. Security in a Full-Stack Application

Security must exist at every layer.

Frontend

Avoid exposing sensitive information.

Backend

Validate input and authenticate users.

API

Implement authorization and rate limiting where appropriate.

Database

Use restricted database accounts and secure credentials.

SQL

Use parameterized queries.

Authentication

Hash passwords securely and protect sessions or tokens.

Deployment

Use HTTPS and secure environment variables.

Security isn't one feature that can simply be added at the end.

It is an architectural responsibility.

22. Development Workflow

A practical development workflow might look like this:

1. Design database schema
2. Build backend API
3. Test API
4. Build React interface
5. Connect frontend to API
6. Add authentication
7. Add validation
8. Add error handling
9. Optimize database queries
10. Test complete application
11. Deploy
12. Monitor

Developers can use Git to track changes throughout the process.

A typical repository might look like:

my-fullstack-app/
│
├── frontend/
│   ├── src/
│   ├── components/
│   └── pages/
│
├── backend/
│   ├── routes/
│   ├── controllers/
│   ├── services/
│   └── middleware/
│
├── database/
│   └── migrations/
│
└── README.md

The exact structure varies between projects, but separating responsibilities helps maintainability.

23. Testing the Full Stack

Testing should happen at different levels.

Frontend Testing

Test components and user interactions.

API Testing

Test endpoints independently.

For example:

POST /api/login
GET /api/users
POST /api/tasks
DELETE /api/tasks/:id

Database Testing

Verify that queries produce the expected results.

Integration Testing

Test whether multiple components work together.

End-to-End Testing

Simulate the experience of a real user.

For example:

Open application
↓
Register
↓
Login
↓
Create task
↓
Edit task
↓
Complete task
↓
Logout

The goal isn't simply to test individual functions.

It's to verify that the complete system behaves correctly.

24. Deployment

Once the application works locally, it needs to be deployed.

A typical production architecture might look like:

User
 ↓
Frontend Hosting / CDN
 ↓
React Application
 ↓
Backend API
 ↓
PostgreSQL

The frontend and backend can be deployed separately or together depending on the architecture.

The production database should have appropriate:

Backups
Access controls
Monitoring
Connection limits
Environment configuration

Deployment is not the end of development.

Production systems require monitoring and maintenance.

25. Logging and Monitoring

When something goes wrong in production, developers need information about what happened.

Backend logging can record events such as:

Request received
User authenticated
Database query executed
Response returned
Error occurred

Monitoring tools can help identify:

Slow API responses
High database usage
Server errors
Failed requests
Memory problems
Traffic spikes

A production application without observability can be extremely difficult to maintain.

26. The Most Important Skill: Understanding the Boundaries

Learning React, Node.js, Express, and PostgreSQL individually is useful.

But the most important full-stack skill is understanding where responsibility belongs.

React should focus primarily on presentation and user interaction.

The backend should handle business rules, authentication, authorization, and API behavior.

PostgreSQL should handle persistent data and relational operations.

For example:

React:
"What did the user click?"

Backend:
"Is this action allowed?"

Database:
"What information should be stored?"

When responsibilities are clearly separated, applications become easier to understand and maintain.

27. What Happens When You Click a Button?

Let's summarize the entire process using one simple example.

A user clicks:

"Complete Task"

React detects the click.

fetch("/api/tasks/15", {
  method: "PATCH",
  body: JSON.stringify({
    completed: true
  })
});

The request travels to the backend.

Express identifies the route.

The backend verifies the user's authentication.

The backend validates the input.

The server sends a parameterized SQL query:

UPDATE tasks
SET completed = $1
WHERE id = $2
RETURNING *;

PostgreSQL executes the query.

The database returns the updated task.

The backend converts the result into JSON.

React receives the response.

React updates its state.

The interface changes from:

☐ Learn PostgreSQL

to:

☑ Learn PostgreSQL

The user sees the result almost instantly.

That tiny interaction represents the entire full stack architecture working together.

28. What Should a Beginner Learn First?

If you're starting full-stack development, don't try to master everything simultaneously.

A practical learning path is:

Step 1: HTML and CSS

Understand the structure and styling of websites.

Step 2: JavaScript

Learn variables, functions, arrays, objects, asynchronous programming, modules, and modern JavaScript.

Step 3: React

Learn:

Components
Props
State
Hooks
Forms
Routing
API requests

Step 4: Node.js and Express

Learn:

HTTP
REST APIs
Middleware
Authentication
Validation
Error handling

Step 5: PostgreSQL

Learn:

Tables
Primary keys
Foreign keys
CRUD
JOINs
Indexes
Transactions
Database design

Step 6: Full-Stack Projects

Build applications that connect everything together.

For example:

Task manager
Blog platform
Ecommerce application
CRM
Job board
Inventory system
Project management platform

Building projects is where the concepts become real skills.

29. The Future of Full-Stack Development

Modern full-stack development continues to evolve.

Developers now have access to powerful frameworks, managed databases, cloud platforms, serverless infrastructure, AI coding assistants, and automated deployment systems.

However, the fundamental architecture remains remarkably consistent:

User
 ↓
Interface
 ↓
API
 ↓
Business Logic
 ↓
Database

Tools will change.

Frameworks will change.

Programming languages will evolve.

But understanding how data moves through a software system will remain valuable.

A developer who understands the complete lifecycle of a request can adapt to new technologies much more easily.

Conclusion

Going from React to PostgreSQL is not simply about learning four different technologies.

It's about understanding how an entire software system works.

React creates the interface.

The browser sends requests.

The backend receives those requests.

Business logic determines what should happen.

The API communicates with the database.

PostgreSQL stores and retrieves information.

The backend returns a response.

React updates the interface.

This cycle happens repeatedly throughout almost every modern data-driven web application.

The real power of full stack development comes from understanding the connections between these layers.

You don't need to become an expert in everything immediately. Start with the fundamentals, build small applications, understand how each layer communicates with the next, and gradually introduce more advanced concepts such as authentication, database relationships, caching, indexing, transactions, testing, and deployment.

Once you understand the journey from a user's click in React to a SQL query in PostgreSQL and back again you stop thinking about technologies as isolated tools.

You start thinking like a full stack developer.

And that shift in perspective is one of the most valuable skills you can develop in modern software engineering.

Securing the MyZubster Metaverse: From Stateless JWTs to Revocable Sessions

Mon, 28 Sep 2026 12:31:55 +0000

Securing the MyZubster Metaverse: From Stateless JWTs to Revocable Sessions
We have completed another major security milestone for the MyZubster Metaverse.
The original authentication system depended mainly on browser-stored JWT access tokens. That solution was simple, but it could not provide the session lifecycle controls required by a platform with persistent identities, virtual characters, private rooms, realtime interactions and future Marketplace or payment operations.
Under MYZ-71 — Authentication, Sessions & Account Security, we have now implemented:

persistent server-side sessions;
session-bound JWT access tokens;
real logout;
active-device management;
remote session revocation;
rotating opaque refresh tokens;
refresh-token replay detection;
automatic access-token renewal for the Metaverse;
concurrent refresh deduplication;
origin-based CSRF protection;
structured authentication errors.
The implementation is currently available in a Draft pull request:
https://github.com/danieldirimini-myzubster/myzubster/pull/10
It has not been merged or declared production-ready yet.
Why stateless JWTs were no longer enough
A server can validate a JWT without loading a database session, but a completely stateless design has significant limitations.
A token may remain valid even after:
the user logs out;
the device is no longer trusted;
the password changes;
the account owner wants to disconnect another device;
a security event requires immediate revocation.
Long-lived tokens also increase the impact of credential theft.
If they are stored in localStorage, they are accessible to frontend JavaScript. This makes an XSS vulnerability significantly more dangerous.
We moved toward a hybrid architecture:
User authentication
```
  ↓
```
Persistent server-side session
```
  ↓
```
Short-lived JWT access token
```
  ↓
```
Rotating opaque refresh token
```
  ↓
```
Automatic renewal
```
  ↓
```
Replay detection and revocation
The JWT is still useful, but the persistent session is now the final source of authority.
Persistent server-side sessions
Each authenticated device receives its own MongoDB AuthSession.
A session records:
the session identifier;
the owning user;
creation and expiration timestamps;
last activity;
limited device metadata;
a privacy-preserving network digest;
revocation time and reason;
the current refresh-token hash;
previously consumed refresh-token hashes;
refresh-token rotation metadata.
MongoDB TTL indexing is used to remove expired sessions automatically.
A valid JWT is rejected when its corresponding session is missing, expired or revoked.
Binding access tokens to sessions
New access tokens include a server-generated sid claim.
A simplified token looks like this:
{
"sub": "user-id",
"sid": "session-uuid",
"jti": "access-token-uuid",
"iat": 1790540000,
"exp": 1790540900
}
Request authentication now consists of two steps:
Verify the JWT
```
↓
```
Validate the server-side session
This provides both efficient request authentication and immediate revocation.
If a device is removed from the account-security interface, its JWT stops working even if it has not reached its expiration time.
Real logout and active-device management
The React frontend now includes:
/account/security
Users can inspect:
active sessions;
the current device;
creation time;
last activity;
expiration time;
limited device information.
They can disconnect another device or terminate their current session.
The supporting endpoints are:
POST /api/auth/logout
GET /api/auth/me
GET /api/auth/me/sessions
DELETE /api/auth/me/sessions/:sessionId
Logout is idempotent.
Even when the access token is expired or malformed, the backend clears the authentication cookies. When possible, the refresh token is used to identify and revoke the persistent session.
Opaque refresh tokens
The refresh token is deliberately not a JWT.
Its conceptual format is:
myzr.<session-id>.<cryptographically-random-secret>
The raw token is never stored in MongoDB.
The backend calculates:
HMAC-SHA256(server secret, raw refresh token)
Only the resulting digest is persisted.
If the session database is exposed, an attacker cannot directly use the stored digest to renew a session.
Atomic refresh-token rotation
Refresh tokens are single-use.
When the browser calls:
POST /api/auth/refresh
the server:
1. reads the HttpOnly refresh cookie;
2. extracts the session identifier;
3. hashes the submitted token;
4. creates a new random refresh token;
5. atomically compares the submitted hash with the current stored hash;
6. replaces the current hash;
7. stores the consumed hash in a bounded history;
8. issues a new access token;
9. sends new authentication cookies.
  Only one request can successfully consume the current token.
  This prevents ordinary concurrent requests from rotating the same credential more than once.
  Refresh-token replay detection
  The server maintains a bounded history of consumed refresh-token hashes.
  If a previously consumed token appears again, the session is treated as potentially compromised:
  Old refresh token submitted
  ↓
  Replay detected
  ↓
  Entire session revoked
  ↓
  Cookies cleared
  ↓
  New login required
  The revocation reason is recorded as:
  refresh-token-replay
  The history is limited so the MongoDB session document cannot grow indefinitely.
  Automatic renewal in the Metaverse
  We introduced a reusable frontend client:
  authenticatedFetch(input, options)
  The client handles the access-token lifecycle:
  Protected request
  ↓
  401 access-token response
  ↓
  POST /api/auth/refresh
  ↓
  Receive rotated access token
  ↓
  Retry original request once
  The complete Metaverse API module now uses this client.
  It covers operations involving:
profiles;
rooms;
invitations;
sessions;
participants;
stage access;
messages;
moderation;
reports;
landmarks;
realtime world actions.
The client retries only recognized access-token errors and never enters an infinite retry loop.
Deduplicating concurrent refresh operations
A Metaverse page can perform several API requests simultaneously.
When an access token expires, multiple requests may receive a 401 at approximately the same time.
Without coordination, every request could call /api/auth/refresh using the same single-use refresh token. This could produce an accidental replay event.
The client therefore shares one in-flight refresh operation:
Request A → 401 ┐
Request B → 401 ├─→ One refresh
Request C → 401 ┘
```
               ↓
         New access token
               ↓
        Retry A, B and C
```
Tests confirm that two simultaneous protected requests produce exactly one refresh operation and two successful retries.
Handling terminal authentication failures
The client does not silently renew an explicitly revoked session.
For example:
AUTH_SESSION_REVOKED
is returned directly to the application.
If the refresh token is no longer valid, the client:
clears the temporary browser credentials;
emits:
myzubster:auth-expired
The UI can use this event to return the user to authentication without every page implementing its own renewal logic.
CSRF protection
Cookie authentication introduces a different security risk: browsers attach cookies automatically.
State-changing requests must therefore be protected against Cross-Site Request Forgery.
We added an origin-based CSRF guard for unsafe cookie-authenticated methods:
POST
PUT
PATCH
DELETE
The guard evaluates:
Origin;
Referer;
Sec-Fetch-Site;
configured application origins;
the actual request target.
A browser request marked as cross-site is rejected before the backend performs a session lookup:
Sec-Fetch-Site: cross-site
The API returns a structured response:
{
"success": false,
"request_id": "request-uuid",
"error": {
"code": "AUTH_CSRF_REJECTED",
"message": "Origine della richiesta non autorizzata"
}
}
Which routes are protected?
The trusted-origin policy is applied to:
password registration;
password login;
OAuth ticket verification;
social-login ticket exchange;
refresh-token rotation;
logout;
Gmail verification exchange;
protected mutations authenticated through cookies.
Bearer-token clients remain compatible during the migration because they do not depend on automatically attached cookies.
CLI and server-to-server clients that do not send browser origin metadata also remain supported.
Configuring trusted origins
Production and preview origins can be configured with:
AUTH_TRUSTED_ORIGINS=https://www.myzubster.com,https://preview.myzubster.com
The middleware also recognizes:
FRONTEND_URL
PUBLIC_APP_URL
GATEWAY_PUBLIC_URL
Local development accepts:
http://localhost:3000
http://127.0.0.1:3000
These values still need to be verified in the real deployment before the platform switches to cookie-only authentication.
Cookie protections
The authentication cookies use:
HttpOnly
SameSite=Lax
Secure in production
The refresh cookie is restricted to:
Path=/api/auth
This prevents it from being attached to unrelated application requests.
SameSite=Lax provides another security layer, but it is not treated as the only CSRF defence.
Privacy considerations
Raw client IP addresses are not stored.
The server stores an HMAC-derived digest instead. This allows limited correlation for security analysis without retaining the original address as ordinary application data.
Device metadata is also intentionally limited.
A session-security feature should help users recognize their devices without becoming an invasive tracking mechanism.
Validation results
The focused backend security scope passes:
30/30 tests
The focused frontend and Metaverse scope passes:
19/19 tests
The test coverage includes:
persistent session creation;
session-bound JWT validation;
real logout;
remote revocation;
refresh-token hashing;
atomic token rotation;
refresh replay detection;
replay-driven session revocation;
automatic access-token renewal;
exactly-once retry;
concurrent refresh deduplication;
structured authentication failures;
same-origin CSRF acceptance;
configured frontend-origin acceptance;
cross-site CSRF rejection;
rejection before database lookup;
bearer-token compatibility;
non-browser compatibility.
The React production build also completes successfully.
GitHub Actions status
The affected backend suites are green:
tests/authSessionService.test.js
tests/authSessionController.test.js
tests/authMiddlewareSessions.test.js
tests/socialIdentityService.test.js
tests/csrfProtection.test.js
The complete repository currently reports:
142 test suites passed
42 test suites failed

746 tests passed
44 tests failed
The remaining failures belong to existing repository-wide problems involving Zorgax, Marketplace, seller policies and legacy Metaverse expectations.
The new authentication implementation is green in its affected scope, but the pull request remains a Draft because the repository as a whole is not yet CI-clean.
What is completed?
Persistent server-side sessions DONE
Session-bound access tokens DONE
Real logout DONE
Active-device management DONE
Remote session revocation DONE
Rotating opaque refresh tokens DONE
Refresh-token replay detection DONE
Password and social authentication DONE
Account-security interface DONE
Metaverse automatic renewal DONE
Concurrent refresh deduplication DONE
Origin-based CSRF protection DONE
Structured authentication errors DONE
Focused automated testing DONE
What is still missing?
Renewal outside the Metaverse
Some Marketplace, Zorgax, profile and administrative pages still use direct fetch calls and manually constructed bearer headers.
They need to be migrated to authenticatedFetch.
Removal of localStorage authentication
Browser storage remains as a temporary migration bridge.
The final architecture should avoid exposing reusable credentials to frontend JavaScript.
Before removing it, we must migrate:

all authenticated API clients;
protected React pages;
realtime connections;
embedded or mobile clients;
legacy user sessions.
Production trusted-origin validation
The public deployment must verify:
exact frontend origins;
preview domains;
reverse-proxy host and protocol forwarding;
cookie paths;
cross-site rejection;
same-origin refresh;
session revocation;
deliberate replay detection.
Strict session enforcement
After legacy tokens have expired, we can enable:
REQUIRE_SERVER_SESSION=true
JWTs without a valid persistent session will then be rejected.
Passkeys and magic links
MYZ-71 still includes passwordless authentication.
Passkeys require complete WebAuthn support for:
challenge generation;
relying-party configuration;
allowed origins;
credential counters;
credential revocation;
recovery.
Magic links require short-lived, single-use verification tokens.
Step-up authentication
Sensitive operations should require recent stronger authentication.
Possible examples include:
changing an email address;
changing a password;
registering or deleting passkeys;
deleting an account;
wallet operations;
payment approval;
sensitive Marketplace changes.
Production OAuth and database validation
Google, GitHub and Facebook authentication must still be tested using the production callback URLs and secrets.
MongoDB Atlas must be checked for:
TTL-index creation;
refresh-token indexes;
document growth;
expired-session cleanup;
concurrent rotation;
rolling-deployment compatibility.
Recommended next steps
1. Review the Draft pull request
2. Configure production trusted origins
3. Deploy with migration compatibility enabled
4. Verify cookies and database indexes
5. Test automatic Metaverse renewal
6. Test concurrent refresh requests
7. Test cross-site rejection
8. Test deliberate refresh-token replay
9. Migrate the remaining frontend API clients
10. Allow legacy tokens to expire
11. Remove tokens from localStorage
12. Enable strict session enforcement
13. Remove bearer migration support
14. Add passkeys, magic links and step-up authentication
  Final thoughts
  Authentication security is not just about issuing a JWT.
  A complete system must manage the entire lifecycle:
  Authenticate
  Create
  Validate
  Renew
  Observe
  Revoke
  Recover
  Monitor
  MyZubster now has the foundations for secure multi-device sessions, refresh-token rotation, replay detection, automatic Metaverse renewal and browser-origin protection.
  The next challenge is deployment and migration: validate the public environment, move the remaining clients to the shared authentication layer and eliminate browser-accessible credentials.
  Draft pull request:
  https://github.com/danieldirimini-myzubster/myzubster/pull/10

MyZubster #Metaverse #CyberSecurity #Authentication #NodeJS #ReactJS #MongoDB #JWT #CSRF #WebSecurity #SoftwareArchitecture #OpenSource

From Stateless JWTs to Revocable Sessions: Securing the MyZubster Metaverse

Sun, 27 Sep 2026 18:29:37 +0000

From Stateless JWTs to Revocable Sessions: Securing the MyZubster Metaverse
MyZubster is developing a persistent open-source digital ecosystem that connects verified identities, metaverse characters, community missions, knowledge, marketplaces, and contributor activity.
As the platform grows, authentication can no longer mean simply issuing a JSON Web Token and trusting it until it expires.
A persistent metaverse requires a stronger security model:

real server-side logout;
session and device management;
remote revocation;
privacy-preserving activity metadata;
secure browser cookies;
structured authentication errors;
compatibility with existing clients;
a path toward passkeys and rotating refresh tokens.
We have now implemented the first major security slice of MYZ-71 — Authentication, sessions and account security.
The implementation is available in the following draft pull request:
MYZ-71: Add revocable sessions and device security controls
The pull request is still a draft. It has not been merged or deployed to production.
Why stateless JWTs were no longer enough
The previous authentication architecture issued a signed JWT containing information such as:
{
"userId": "USER_ID",
"username": "daniel",
"role": "user",
"iat": 1789970000,
"exp": 1790574800
}
The server could validate the signature and expiration time, but it could not immediately answer several important security questions:
Did the user log out?
Was the device remotely revoked?
Is the token associated with a known active login?
Was the session disabled after the token was created?
Which browser created the session?
Should this token be rejected before its cryptographic expiration?
A purely stateless JWT remains valid until it expires. Logging out in the browser may remove a local token, but it does not necessarily invalidate a copied token.
That limitation becomes especially important when an account controls:
a persistent metaverse character;
private rooms;
creator permissions;
marketplace activity;
verified social identities;
community moderation;
contributor or reward-related actions.
The new hybrid architecture
We retained JWTs, but every newly issued JWT is now connected to a persistent server-side session.
The new token includes two identifiers:
{
"userId": "USER_ID",
"username": "daniel",
"role": "user",
"sid": "4cb9c3a1-8d39-4f2d-8a91-82c9556abc91",
"jti": "48ab2bd5-b4fa-426a-af42-3e24758e0434",
"iat": 1789970000,
"exp": 1790574800
}
The sid claim identifies the persistent session. The jti uniquely identifies the issued JWT.
Authentication now follows this sequence:
Request
↓
Extract token from secure cookie or Authorization header
↓
Verify JWT signature and expiration
↓
Read the sid claim
↓
Find the corresponding server-side session
↓
Verify ownership, expiration and revocation state
↓
Allow or reject the request
A valid JWT is no longer sufficient when its server-side session has been revoked or expired.
Persistent AuthSession records
A new MongoDB model stores the authentication state.
Conceptually, the model contains:
{
sessionId: String,
userId: ObjectId,
userAgent: String,
ipHash: String,
createdAt: Date,
lastSeenAt: Date,
expiresAt: Date,
revokedAt: Date,
revokedReason: String
}
Session creation
Every password or social login creates a cryptographically random session identifier:
const sessionId = crypto.randomUUID();
A JWT is then signed with that identifier:
const token = jwt.sign(
{
userId: String(user._id),
username: user.username,
role: user.role,
sid: sessionId
},
jwtSecret,
{
expiresIn: sessionTtl,
jwtid: crypto.randomUUID()
}
);
The session document and token are created as part of the same authentication flow.
Expiration enforcement
The session contains an explicit expiration timestamp and a MongoDB TTL index.
However, MongoDB TTL cleanup is asynchronous. An expired document may remain in the collection temporarily.
For this reason, authentication never relies only on physical deletion. The validation query requires:
{
sessionId: decoded.sid,
userId: decoded.userId,
revokedAt: null,
expiresAt: { $gt: new Date() }
}
The session becomes unusable immediately after expiration, even if MongoDB has not deleted it yet.
Revocation
Revocation does not delete the session immediately. Instead, the server records when and why it was revoked:
{
revokedAt: new Date(),
revokedReason: "user-revoked"
}
Keeping this state is useful for security analysis and makes the revocation operation auditable.
Privacy-preserving IP metadata
The server does not store raw IP addresses.
When an address is available, it is converted into an HMAC-SHA256 digest:
const ipHash = crypto
.createHmac("sha256", SESSION_IP_HASH_SECRET)
.update(ipAddress)
.digest("hex");
This allows the application to identify meaningful changes between login contexts without creating a database of clear-text IP addresses.
The HMAC secret prevents the value from behaving like a simple unsalted hash that could be easily precomputed.
Last-activity tracking without excessive writes
The session records lastSeenAt, but it is not updated on every request.
Updating the database for every authenticated API call would create unnecessary write volume.
Instead, the timestamp is refreshed only when the previous update is older than five minutes:
if (Date.now() - lastSeenAt > FIVE_MINUTES) {
await AuthSession.updateOne(
{
```
sessionId: decoded.sid,
revokedAt: null
```
},
{
```
$set: {
  lastSeenAt: new Date()
}
```
}
);
}
This provides useful account activity information while reducing database pressure.
Secure cookies and compatibility mode
The authentication token can now be received from either:
Authorization: Bearer TOKEN
or the following browser cookie:
myzubster_session
The cookie uses these properties:
{
httpOnly: true,
secure: production,
sameSite: "lax",
path: "/",
maxAge: sessionTtl
}
Why use HttpOnly?
Browser JavaScript cannot directly read an HttpOnly cookie.
This limits simple token extraction through code such as:
document.cookie
It does not solve every XSS scenario, but it substantially reduces the exposure of authentication secrets.
Why bearer tokens are still supported
MyZubster already has clients that use tokens stored by older authentication flows.
Removing bearer support immediately would invalidate existing sessions and potentially break multiple parts of the frontend.
The system therefore supports a migration period:
Legacy client
→ Authorization: Bearer

New browser session
→ HttpOnly myzubster_session cookie
Older JWTs may also lack an sid claim. They remain temporarily compatible unless strict mode is enabled:
REQUIRE_SERVER_SESSION=true
Once existing tokens have expired, strict mode can reject every JWT that is not connected to a server session.
New authentication endpoints
Four important endpoints were added.
Current account
GET /api/auth/me
Returns the authenticated user and associated public character information.
Active devices and sessions
GET /api/auth/me/sessions
Example response:
{
"success": true,
"request_id": "bf7a957e-1669-4432-a9a4-e686cb70cc07",
"sessions": [

{
  "id": "4cb9c3a1-8d39-4f2d-8a91-82c9556abc91",
  "current": true,
  "device": "Mozilla/5.0 ...",
  "createdAt": "2026-09-27T08:00:00.000Z",
  "lastSeenAt": "2026-09-27T09:00:00.000Z",
  "expiresAt": "2026-10-04T08:00:00.000Z"
}

]
}
Only sessions belonging to the authenticated user are returned.
Revoke a session
DELETE /api/auth/me/sessions/:sessionId
The update is scoped by both the user and session identifier:
{
userId: authenticatedUserId,
sessionId,
revokedAt: null
}
This prevents one account from revoking another user’s session.
Logout
POST /api/auth/logout
Logout is deliberately idempotent.
The cookie is cleared even when the submitted token is:

expired;
malformed;
already revoked;
disconnected from a server session.
The logout route is intentionally not protected by the standard authentication middleware. Otherwise, an expired token could be rejected before the handler had an opportunity to clear the invalid cookie.
When a valid session is available, logout also revokes it server-side.
Structured authentication errors
Authentication errors now use stable public codes instead of exposing raw JWT library messages.
Example:
{
"success": false,
"request_id": "5fe11522-c804-4907-a4d1-0f459f94ab2a",
"error": {
"code": "AUTH_SESSION_REVOKED",
"message": "Session expired or revoked"
}
}
Current error categories include:
AUTH_TOKEN_MISSING
AUTH_TOKEN_INVALID
AUTH_TOKEN_EXPIRED
AUTH_SESSION_REVOKED
Each response contains a request ID that can be correlated with server logs.
This is useful for debugging while avoiding the disclosure of stack traces, signing details, or internal JWT parsing errors.
Integration with social authentication
Persistent sessions are now created for:
registration;
password login;
Google login;
GitHub login;
Facebook login.
The social OAuth ticket exchange now creates the same server-side session used by password authentication and sets the secure cookie.
During integration testing, we also corrected two existing issues.
GitHub profile persistence
An undefined nested GitHub public-profile snapshot could cause a Mongoose casting error.
The new implementation updates nested data explicitly and writes the public snapshot only when a defined value is available.
Facebook accounts without email
Not every Facebook account exposes an email address.
MyZubster already supported a deterministic private relay identity for this situation. The integration tests were aligned with that intended behavior instead of incorrectly requiring every account to provide an email.
The relay value is treated as an internal identifier, not as a verified personal email.
The account-security interface
A new React page is available at:
/account/security
It displays:
the authenticated account;
all active devices;
the current device;
session creation time;
last activity;
session expiration;
controls for remote revocation;
current-session termination;
logout.
The page is linked from:
the authenticated account panel on the MyZubster home interface;
the Neon Plaza metaverse top bar.
Frontend API module
The React application uses a dedicated session API:
getCurrentAccount();
getAuthSessions();
revokeAuthSession(sessionId);
logoutCurrentSession();
clearBrowserAuth();
Requests include same-origin cookies:
fetch(path, {
credentials: "same-origin",
headers: {
...bearerMigrationFallback
}
});
Structured server errors are preserved so the UI can display a support request ID when an operation fails.
Remote device revocation
When the user revokes another device:
1. the UI requests confirmation;
2. a session-specific DELETE request is sent;
3. the server verifies session ownership;
4. the session receives a revocation timestamp;
5. the frontend removes it from the active list;
6. the revoked device is rejected on its next request.
  Current-device termination
  Terminating the current session:
7. revokes the server-side session;
8. clears the secure cookie;
9. removes legacy browser credentials;
10. redirects the user through authentication again.
  Legacy browser keys removed during logout include:
  myzubster-token
  token
  accessToken
  myzubster-user
  myzubster-identity-provider
  myzubster-metaverse-character-id
  Protected production routing
  The new account page is configured as an explicit Vercel SPA route.
  It includes:
  X-Robots-Tag: noindex, nofollow
  Account-security pages should not be indexed, cached as search snippets, or treated as public content.
  Both the root and standalone frontend Vercel configurations were updated and validated as JSON.
  Testing and verification
  Backend
  Five focused backend suites pass:
  authSessionService
  authMiddlewareSessions
  authSessionController
  socialAuthCallback
  socialIdentityService
  Results:
  5 suites passed
  24 tests passed
  Coverage includes:
persistent session creation;
bearer and cookie extraction;
active-session validation;
revoked-session rejection;
token-expiration handling;
structured errors;
session listing;
remote revocation;
valid logout;
malformed-token logout;
Google authentication;
GitHub authentication;
Facebook authentication;
persistent metaverse characters.
The social identity tests use MongoDB Memory Server so the persistence behavior is exercised rather than completely mocked.
Frontend
Three focused frontend suites pass:
authSessions API
AccountSecurityPage
MetaversePage
Results:
3 suites passed
11 tests passed
The tests cover:
same-origin credentials;
bearer-token migration;
safe session-ID encoding;
structured server errors;
local credential cleanup;
account and session rendering;
current-device labeling;
remote revocation;
removal of revoked devices;
safe date formatting;
existing Neon Plaza mission-state behavior.
The React production bundle also compiles successfully.
Repository-wide CI status
The pull request remains a draft because repository-wide CI still contains failures outside this authentication change.
A previous complete run reported:
149 test suites passed
34 test suites failed

774 tests passed
44 tests failed
The sampled failures were primarily related to existing:

Zorgax payment code;
cultural modules;
Kefir workflows;
Marketplace contract assertions;
realtime behavior;
observability source assertions.
The dependency audit also reports vulnerabilities from the unchanged lockfile. This authentication work does not modify package.json or package-lock.json.
These failures should remain visible, but unrelated systems should not be rewritten inside an authentication PR without appropriate scope and review.
What remains to be implemented
This pull request does not complete MYZ-71.
Rotating refresh tokens
The final architecture should use:
Short-lived access token
```
  +
```
Rotating refresh token
The refresh token should:
be cryptographically random;
be stored only as a hash;
belong to a token family;
be consumed exactly once;
rotate after every refresh;
detect reuse;
revoke the family after suspected replay.
A conditional database operation will be necessary to prevent two simultaneous requests from consuming the same token successfully.
Passkeys and WebAuthn
The planned API includes:
POST /api/auth/start
POST /api/auth/verify
Passkey verification must validate:
the challenge;
origin;
relying-party ID;
credential ID;
public-key signature;
authenticator data;
user presence;
user verification;
authenticator signature counters.
The account UI will also need credential listing, naming and revocation.
Magic-link authentication
Magic links require:
single-use random challenges;
hashed challenge storage;
short expiration;
rate limiting;
account-enumeration resistance;
safe redirect validation;
protection against email link scanners;
invalidation after first use.
Step-up authentication
Sensitive operations should require recent stronger authentication.
Examples include:
changing an email address;
changing payment information;
adding or removing passkeys;
exporting sensitive data;
changing privileges;
deleting an account.
The server will need to distinguish between a valid session and a recently re-verified session.
CSRF protection
SameSite=Lax is a useful baseline, but it is not the complete strategy for a cookie-authenticated application.
Before the system becomes cookie-only, state-changing requests should add explicit protection through techniques such as:
origin validation;
synchronizer tokens;
signed double-submit cookies;
required custom headers.
Removing browser-readable tokens
Bearer compatibility and local-storage cleanup exist for migration purposes.
The intended final browser architecture is:
Credentials:
HttpOnly secure cookies

Frontend JavaScript:
no direct access to reusable authentication secrets
Once the migration period ends, MyZubster should stop returning long-lived authentication tokens to frontend JavaScript.
Production validation
The following checks remain:

secure cookie verification on the public HTTPS domain;
remote revocation between two physical devices;
GitHub OAuth callback verification in production;
Google and Facebook regression checks;
MongoDB TTL-index verification;
investigation of intermittent Atlas ReplicaSetNoPrimary events;
strict-session migration testing;
request-ID propagation through production logs and proxies.
Why this is important for the metaverse
Authentication is not separate from the metaverse. It is the foundation of persistent identity.
The MyZubster identity chain is becoming:
MyZubster account
↓
Revocable server session
↓
Verified character
↓
Neon Plaza participation
↓
Missions and contributions
↓
Knowledge, marketplace and community activity
If a token is stolen, revocation must also protect the connected metaverse character and its permissions.
This session infrastructure prepares the platform for:
private metaverse rooms;
verified contributors;
creator permissions;
moderation roles;
university pilots;
community governance;
marketplace actions;
development requests;
contribution evidence.
Current status
Implemented:
persistent authentication sessions;
JWT-to-session binding;
secure cookies;
bearer-token migration;
session expiration;
device listing;
remote revocation;
server-side logout;
privacy-preserving IP hashing;
structured errors and request IDs;
social-login integration;
account-security UI;
Neon Plaza integration;
protected Vercel routing;
focused backend and frontend tests.
Still required:
refresh-token rotation;
replay detection;
passkeys;
magic links;
step-up authentication;
CSRF hardening;
removal of browser-readable credentials;
production OAuth verification;
Atlas stability verification;
repository-wide CI cleanup.
This is an important security milestone, but it is not a declaration that authentication is finished.
The goal is to make every security claim testable, observable and reversible during rollout.
In MyZubster, trust should not depend on promises. It should be built through verifiable behavior.
Suggested Coder Legion tags:
Cybersecurity
Node.js
React
Web Development
Authentication
Metaverse
Suggested excerpt:
How MyZubster is moving from stateless JWT authentication to persistent, revocable sessions with secure cookies, device management, structured errors, social-login integration and a React account-security dashboard.

One Design System, Two Runtimes: Sharing Contracts Between React and React Native

Sat, 26 Sep 2026 09:42:11 +0000

A cross-platform design system sounds simple until the first real component forces the platforms apart.

React and React Native can expose the same product concept — a button, checkbox, input, modal — while relying on very different runtime primitives. The web has DOM attributes, anchors, CSS, hover and keyboard behavior. React Native has Pressable, native accessibility props, gesture events, and a completely different styling model.

Trying to hide all of those differences behind one implementation usually makes the API worse. In Vellira, I have been taking a different approach: share the semantic contract, not the runtime implementation.

That distinction has become one of the most useful architectural rules in the project.

The real goal is consistency, not identical code

When I started building Vellira, it was tempting to think about cross-platform components mainly as a code-sharing problem.

If a web button and a native button look similar, why not make them use as much of the same component code as possible?

Because the important thing users consume is not the internal component tree. It is the behavior and mental model of the public API.

For a button, developers should be able to learn concepts such as:

color
appearance
size
shape
loading
disabled
fullWidth
iconOnly

once and carry that knowledge between platforms.

The implementation underneath those concepts does not need to be the same.

This leads to a more useful definition of parity:

Cross-platform parity means shared semantics where the platforms agree, plus explicit platform-specific capabilities where they do not.

That is much stronger than forcing two different runtimes through the same abstraction.

Put shared semantics in a platform-neutral contract

Vellira keeps the common Button vocabulary in @vellira-ui/types.

A simplified view of the shared contract looks like this:

export type ButtonSize = 'sm' | 'md' | 'lg';

export type ButtonColor =
  | 'primary'
  | 'neutral'
  | 'success'
  | 'warning'
  | 'danger';

export type ButtonAppearance =
  | 'solid'
  | 'outline'
  | 'ghost'
  | 'soft'
  | 'link';

export interface BaseButtonProps {
  color?: ButtonColor;
  appearance?: ButtonAppearance;
  size?: ButtonSize;
  shape?: 'square' | 'rounded' | 'pill';
  fullWidth?: boolean;
  loading?: boolean;
  loadingText?: string;
  disabled?: boolean;
  iconOnly?: boolean;
}

There is nothing web-specific or native-specific in that interface. It describes what a Vellira button means.

That shared layer gives both implementations a stable semantic center. If appearance="soft" exists on both platforms, it should represent the same design intent. If loading disables interaction, that rule should be understood consistently too.

This is where I want reuse to be strongest.

Let each platform extend the contract honestly

Once the common semantics are defined, the platform packages can extend them instead of pretending their runtimes are identical.

On the web, ButtonProps extends the shared contract and normal HTML button behavior. It can also expose anchor-related properties such as href, target, and rel.

export interface ButtonProps
  extends
    BaseButtonProps,
    Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'color'>,
    Pick<
      AnchorHTMLAttributes<HTMLAnchorElement>,
      'href' | 'target' | 'rel' | 'download'
    > {
  children?: ReactNode;
  iconStart?: ReactNode;
  iconEnd?: ReactNode;
  tooltip?: string;
  badge?: ReactNode;
  shortcut?: ReactNode;
  asChild?: boolean;
}

React Native starts from the same BaseButtonProps, but the runtime-specific surface is different. It builds on PressableProps, exposes onPress, native styles, and accessibility properties that belong to the native platform.

export interface ButtonProps
  extends BaseButtonProps, Omit<PressableProps, /* platform exclusions */> {
  children?: ReactNode;
  iconStart?: ButtonIconElement;
  iconEnd?: ButtonIconElement;
  iconSize?: number;
  onPress?: (event: GestureResponderEvent) => void;
  style?: StyleProp<ViewStyle>;
  textStyle?: StyleProp<TextStyle>;
  accessibilityLabel?: string;
  testID?: string;
}

The two APIs are clearly related, but they are not artificially identical.

That is intentional.

A web developer still gets normal web capabilities. A React Native developer still gets normal native capabilities. The design system owns the common semantics without becoming an abstraction tax on either platform.

Healthy divergence is part of a good cross-platform API

Some differences should not be normalized away.

For example, a web button can naturally compose with an anchor or another DOM element. That is where properties such as href or Vellira's asChild capability make sense.

React Native does not have an HTML anchor element. Inventing a fake href prop just to make the type signatures look more symmetrical would create parity on paper while making the native API less natural.

The same rule applies in the opposite direction. React Native has concepts such as StyleProp<ViewStyle>, testID, and native press events. Wrapping every one of those in invented cross-platform names would make the system harder to understand and harder to debug.

So I use a simple test when deciding whether something belongs in the shared contract:

Does this property describe product-level component behavior, or does it describe the runtime that implements it?

Product-level behavior is a strong candidate for the shared layer. Runtime behavior usually stays with the platform package.

That distinction keeps the common API small enough to remain meaningful.

Component props are only one layer of cross-platform consistency.

Visual decisions such as spacing, radii, typography scales, colors, and semantic states also need a common source of truth. Those decisions can be represented as tokens and consumed differently by CSS on the web and native style objects in React Native.

The important architectural point is the same: share the decision, adapt the execution.

A radius token does not require the web and native styling engines to work the same way. It only requires both implementations to resolve the same design intent.

This is a useful pattern because it prevents "cross-platform" from turning into "lowest common denominator". Shared semantics stay centralized while each renderer remains free to use the platform correctly.

Test parity at the contract boundary

Once implementations are separate, drift becomes the next problem.

It is easy for the web Button to gain a new appearance or loading rule while the React Native Button silently falls behind. Separate implementations therefore need explicit validation around the things that are supposed to stay aligned.

In Vellira, both Button implementations have their own tests and Storybook coverage. The shared types define a common vocabulary, while platform tests verify actual runtime behavior.

That gives two different kinds of confidence:

Contract confidence — the shared semantic API is defined in one place.
Runtime confidence — each implementation proves that the contract behaves correctly on its own platform.

I prefer this over a large shared implementation with a growing number of platform conditionals. A shared file can look beautifully DRY while still hiding platform-specific bugs.

Separate runtime tests make those differences visible.

A practical three-layer model

The pattern I am converging on in Vellira can be summarized as three layers.

1. Shared semantics

Define the concepts developers should learn once:

size
appearance
color
loading
disabled
shape

These belong in platform-neutral types and design contracts.

2. Platform API

Extend those concepts with capabilities developers expect from the runtime:

Web:          href, target, DOM attributes, asChild
React Native: onPress, accessibilityLabel, style, testID

Do not disguise real platform differences.

3. Platform implementation

Use the native tools of each runtime:

Web:          DOM + CSS
React Native: Pressable + native styles

The implementation can diverge significantly as long as the shared semantics remain trustworthy.

What this changes when designing new components

This architecture also changes how I think about adding components.

Instead of beginning with "How can I reuse the most code?", I begin with questions like:

What behavior is actually common to both platforms?
Which names should mean the same thing everywhere?
Which states must have equivalent semantics?
Which capabilities are genuinely platform-specific?
What should be validated so parity cannot drift accidentally?

Only after those questions are answered does implementation reuse become interesting.

Sometimes there will be useful shared code below the component layer. Sometimes the correct answer is two mostly independent implementations. Both are acceptable if the public contract stays coherent.

This makes the design system easier to evolve because platform differences are treated as architecture inputs, not inconvenient exceptions.

The rule I keep coming back to

The most useful lesson so far is that cross-platform design systems do not need maximum code sharing. They need maximum semantic clarity.

Developers should feel that the React and React Native packages belong to the same system. They should recognize the vocabulary, states, design decisions, and interaction intent. But they should not have to give up the strengths of their platform to get that consistency.

For Vellira, that means sharing contracts aggressively and implementations selectively.

It is a smaller abstraction, but a much more durable one.

You can explore the project in the Vellira documentation or browse the implementation on GitHub.

Stop Wasting Days on Dev Setup: How We Automated Our Microservices Environment for Every Developer

Thu, 24 Sep 2026 01:52:08 +0000

Stop Wasting Days on Dev Setup: How We Automated Our Microservices Environment for Every Developer

How we reduced new developer onboarding from 3 days to 15 minutes and eliminated configuration drift across 12 microservices.

The Problem That Made Us Snap

Picture this: A new senior developer joins your team. They're excited, ready to ship code on day one. Then reality hits.

Day 1: They spend 6 hours installing Node, Docker, configuring ESLint to match the team's style, figuring out which environment variables go where, and asking Slack questions like "which version of NestJS are we on again?"

Day 2: They finally get user-service running, but auth-service throws a CORS error because their local config is slightly different from everyone else's. They spend the afternoon comparing .env files with a teammate.

Day 3: They submit their first PR. The CI pipeline fails because their local Prettier config formats code differently from the shared config that was updated last month — but nobody told them.

Sound familiar?

We had 12 microservices, a team that was growing fast, and a configuration mess that was eating our productivity alive. Every service had slightly different ESLint rules, Docker setups, folder structures, and VS Code settings. Senior developers were spending hours every week answering setup questions instead of building features.

So we built a system that fixed all of it. Here's exactly how.

The Solution: One Repo to Rule Them All

We created a central configuration repository called dev-environment-config that acts as the single source of truth for every development environment across our entire microservices ecosystem.

The idea is simple:

One repository controls the setup, structure, linting, Docker config, VS Code settings, and shared code for every service. When a senior developer updates it, every developer's machine automatically syncs the next morning.

The Architecture at a Glance

dev-environment-config (Central Repo)
├── templates/          → Project scaffolding (NestJS, React)
├── shared/             → ESLint, Prettier, Git configs
├── vscode/             → Extensions & settings
├── docker/             → Base Docker configs
├── scripts/            → Automation (setup, sync, update)
├── common-lib/         → Shared NPM package
└── manifest.json       → Version tracking

         │  syncs to
         ▼
┌──────────┐ ┌──────────┐ ┌──────────┐
│ user-svc │ │ auth-svc │ │ pay-svc  │  ... 12 services
│ .eslint  │ │ .eslint  │ │ .eslint  │
│ .vscode  │ │ .vscode  │ │ .vscode  │
│ Docker   │ │ Docker   │ │ Docker   │
└──────────┘ └──────────┘ └──────────┘

Implementation: Step by Step

Step 1: The Central Config Repository

We created a new repository with this structure:

dev-environment-config/
├── templates/
│   ├── nestjs-service/    # Complete NestJS starter
│   └── reactjs-service/   # Complete React starter
├── shared/
│   ├── .eslintrc.js
│   ├── .prettierrc
│   ├── .editorconfig
│   ├── .gitignore
│   └── commitlint.config.js
├── vscode/
│   ├── extensions.json
│   ├── settings.json
│   └── launch.json
├── scripts/
│   ├── setup-new-developer.sh
│   ├── sync-config.sh
│   ├── auto-update.sh
│   └── create-new-service.sh
├── common-lib/            # Shared NPM package
└── manifest.json          # Version tracker

The manifest.json is the heartbeat of the system:

{
  "version": "1.2.0",
  "lastUpdated": "2024-01-15T10:00:00Z",
  "updatedBy": "senior-dev",
  "configs": {
    "eslint": "3.2.0",
    "prettier": "2.1.0",
    "docker": "1.5.0"
  },
  "services": [
    "user-service",
    "auth-service",
    "payment-service"
  ]
}

Every time a config changes, we bump the version. This is how the auto-update system knows something changed.

Step 2: The One-Command Onboarding Script

This was the game-changer. We wrote a bash script that a new developer runs once, and their entire environment is ready.

The new developer's experience:

Install VS Code ✅
Run one command:

curl -sSL https://raw.githubusercontent.com/company/\
dev-environment-config/main/scripts/\
setup-new-developer.sh | bash

Wait ~10 minutes. Done.

What the script does under the hood:

#!/bin/bash
set -e

WORKSPACE_DIR="$HOME/company-workspace"
CONFIG_REPO="https://github.com/company/dev-environment-config.git"

echo "🚀 Setting up your development environment..."

# 1. Check & install prerequisites
check_and_install "git" "Git"
check_and_install "node" "Node.js" "nvm install 20"
check_and_install "docker" "Docker"

# 2. Create workspace & clone everything
mkdir -p "$WORKSPACE_DIR" && cd "$WORKSPACE_DIR"
git clone "$CONFIG_REPO"

# 3. Clone all service repos from manifest
SERVICES=$(cat dev-environment-config/manifest.json | \
  python3 -c "import sys,json; \
  [print(s) for s in json.load(sys.stdin)['services']]")

for service in $SERVICES; do
  git clone "https://github.com/company/${service}.git"
done

# 4. Install VS Code extensions
EXTENSIONS=$(cat dev-environment-config/vscode/extensions.json | \
  python3 -c "import sys,json; \
  [print(e) for e in json.load(sys.stdin)['recommendations']]")

for ext in $EXTENSIONS; do
  code --install-extension "$ext" --force
done

# 5. Sync shared configs to all services
bash dev-environment-config/scripts/sync-config.sh

# 6. Install dependencies everywhere
for service in $SERVICES; do
  cd "$service" && npm install && cp .env.example .env && cd ..
done

# 7. Set up daily auto-update cron (8 AM weekdays)
CRON="0 8 * * 1-5 cd $WORKSPACE_DIR && \
  bash dev-environment-config/scripts/auto-update.sh"
(crontab -l 2>/dev/null; echo "$CRON") | crontab -

echo "✅ Setup complete! Open VS Code: code $WORKSPACE_DIR"

That's it. The developer opens VS Code, and everything is configured — extensions, linting, formatting, Docker, environment variables, the works.

Step 3: The Config Sync Script

This script copies the shared configs from the central repo into every service:

#!/bin/bash
# sync-config.sh

CONFIG_ROOT="$(dirname "$SCRIPT_DIR")"
WORKSPACE_DIR="$(dirname "$CONFIG_ROOT")"

for service in $SERVICES; do
  SERVICE_DIR="$WORKSPACE_DIR/$service"

  # Copy shared configs
  cp -f "$CONFIG_ROOT/shared/.eslintrc.js" "$SERVICE_DIR/"
  cp -f "$CONFIG_ROOT/shared/.prettierrc" "$SERVICE_DIR/"
  cp -f "$CONFIG_ROOT/shared/.editorconfig" "$SERVICE_DIR/"
  cp -f "$CONFIG_ROOT/shared/.gitignore" "$SERVICE_DIR/"

  # Copy VS Code settings
  mkdir -p "$SERVICE_DIR/.vscode"
  cp -f "$CONFIG_ROOT/vscode/settings.json" "$SERVICE_DIR/.vscode/"
  cp -f "$CONFIG_ROOT/vscode/extensions.json" "$SERVICE_DIR/.vscode/"

  echo "✅ $service synced"
done

Step 4: The Daily Auto-Update (The Magic)

This is the part that keeps everything in sync without anyone thinking about it.

Every morning at 8 AM (weekdays), a cron job runs auto-update.sh on every developer's machine:

#!/bin/bash
# auto-update.sh — Runs daily at 8 AM

cd "$CONFIG_ROOT"

# 1. Check for config updates
OLD_VERSION=$(cat manifest.json | jq -r '.version')
git pull origin main
NEW_VERSION=$(cat manifest.json | jq -r '.version')

if [ "$OLD_VERSION" != "$NEW_VERSION" ]; then
  echo "🆕 Config updated: $OLD_VERSION → $NEW_VERSION"
  bash "$SCRIPT_DIR/sync-config.sh"
fi

# 2. Pull latest code for all services
for service in $SERVICES; do
  cd "$WORKSPACE_DIR/$service"

  # Stash local changes safely
  git stash push -m "auto-update-$(date +%Y%m%d)" 2>/dev/null

  # Pull latest
  git pull origin $(git branch --show-current) --rebase

  # Update dependencies if package.json changed
  if git diff HEAD~1 --name-only | grep -q "package.json"; then
    npm install
  fi

  # Update shared library
  npm update @company/common-lib
done

# 3. Notify the developer
notify-send "Dev Environment" "✅ Updated to config v$NEW_VERSION"

The flow:

Senior Dev pushes config change
         │
         ▼
   GitHub Actions
         │
    ┌────┴────┐
    │ Slack   │ Notify team
    │ Publish │ common-lib to NPM
    └────┬────┘
         │
    Next 8 AM
         │
         ▼
  Every developer's cron runs
         │
    ┌────┴────────────────┐
    │ Pull config repo    │
    │ Sync shared configs │
    │ Pull service repos  │
    │ Update dependencies │
    │ Desktop notification│
    └─────────────────────┘

Step 5: The Shared Common Library

Instead of copying and pasting guards, interceptors, and DTOs across 12 services, we created @company/common-lib — a private NPM package:

// In any service, just import and use:
import {
  AuthGuard,
  RolesGuard,
  ResponseInterceptor,
  LoggingInterceptor,
  HttpExceptionFilter,
  PaginationDto,
  McpService,        // Qwen MCP integration
} from '@company/common-lib';

@Controller('users')
@UseGuards(AuthGuard, RolesGuard)
@UseInterceptors(ResponseInterceptor)
@UseFilters(HttpExceptionFilter)
export class UserController {
  constructor(private mcpService: McpService) {}

  @Get()
  findAll(@Query() pagination: PaginationDto) {
    return this.userService.findAll(pagination);
  }

  @Post('analyze')
  async analyze(@Body() dto: AnalyzeDto) {
    return this.mcpService.callTool('text-analysis', {
      text: dto.text,
    });
  }
}

When we update the common library (add a new guard, fix a bug in the exception filter), the auto-update system bumps the version in every service automatically.

Step 6: Service Scaffolding

Creating a new microservice used to take a day of copy-pasting and tweaking. Now it takes 30 seconds:

bash scripts/create-new-service.sh

# Prompts:
# Service name: order-service
# Description: Handles order processing
# Port: 3002
# Type: nestjs

# ✅ Done! Complete service with:
# - src/common/ (filters, guards, interceptors, DTOs)
# - Docker setup (Dockerfile + docker-compose)
# - VS Code settings
# - ESLint + Prettier
# - Health check endpoint
# - Swagger docs
# - MCP integration
# - Auto-update scripts

The Benefits (With Real Numbers)

1. Onboarding: 3 Days → 15 Minutes

Before	After
Manual setup following a 40-step Confluence page	One `curl` command
3 days to first productive commit	15 minutes to running all services
"Hey, can you help me with my env vars?" (daily Slack noise)	Zero setup questions

2. Configuration Drift: Eliminated

Before, every service slowly diverged. user-service had ESLint v8, auth-service had v7. Prettier configs had subtle differences. Docker setups were copy-pasted and never updated.

Now, every service has identical configs, and they stay identical because the sync script overwrites them daily.

3. Senior Developer Time: Saved ~5 Hours/Week

Senior devs were spending roughly an hour a day helping juniors with setup issues, reviewing PRs that failed CI due to formatting, and manually updating configs across services.

That time is now spent building features.

4. Consistent Code Quality

Every developer has:

The same ESLint rules (auto-fixed on save)
The same Prettier config (format on save)
The same commit message format (enforced by Husky)
The same VS Code extensions (auto-installed)

PR reviews went from "please fix your formatting" to "let's discuss the architecture."

5. Zero-Effort Config Updates

When a senior developer wants to:

Add a new ESLint rule → Push to config repo → Everyone gets it tomorrow
Update Docker base image → Push → Auto-synced
Add a VS Code extension → Push → Auto-installed
Fix a bug in the exception filter → Publish common-lib → Auto-updated

No Slack announcements needed. No "please run npm install" messages. It just happens.

6. Standardized Project Structure

Every service looks the same. A developer can jump from user-service to payment-service and immediately know where everything is. The src/common/ folder has the same patterns. The Docker setup is identical. The health check endpoint is at the same path.

What We Learned

Start Small

We didn't build this all at once. We started with just syncing ESLint and Prettier configs. Once the team saw the value, we added Docker, VS Code settings, the common library, and the auto-update system incrementally.

Don't Force Everything

We allow service-specific overrides. If payment-service needs a special ESLint rule, they can add a .eslintrc.local.js that extends the shared one. The shared config is the baseline, not a straitjacket.

Notifications Matter

The desktop notification ("✅ Updated to config v1.2.0") was a small touch, but it made developers aware of the system. Before that, updates happened silently and people were confused when things changed.

Version Everything

The manifest.json version tracking was critical. Without it, the auto-update script had no way to know if anything changed, and it would waste time syncing configs that were already up to date.

The Complete Stack

Layer	Technology
Backend	NestJS (TypeScript)
Frontend	ReactJS (TypeScript)
AI	Qwen MCP
Containers	Docker, Docker Compose
Runtime	Node.js 20 LTS
Database	PostgreSQL 16
Cache	Redis 7
CI/CD	GitHub Actions
Editor	VS Code
Config Sync	Bash scripts + Cron

TL;DR

If your team has more than 3 microservices and more than 5 developers, you need a centralized dev environment config. Here's the recipe:

Create a config repo with templates, shared configs, and scripts
Write a setup script that onboards new devs in one command
Write a sync script that copies shared configs to all services
Set up a cron job that auto-updates every morning
Create a shared NPM library for reusable code
Build a service generator for scaffolding new microservices

The result: developers spend their time writing code, not configuring environments.

Have you solved this problem differently at your company? I'd love to hear about it in the comments.

If you found this useful, give it a clap 👏 and follow for more microservices architecture deep-dives.

React Compiler in 2026: Do You Still Need useMemo and useCallback?

Sat, 12 Sep 2026 05:57:58 +0000

Introduction

If you've been following React news this year, you've probably seen React Compiler come up constantly. Since its stable release, adoption has picked up fast, and it's changing a conversation that's been going on in the React community for years: do developers actually need to think about useMemo, useCallback, and React.memo anymore?

Short answer: less than before, but not zero. Let's break down what's actually changed.

What React Compiler Actually Does

React Compiler is a build-time tool that automatically analyzes your components and inserts memoization for you — the same kind of optimization you'd previously write by hand with useMemo and useCallback, except the compiler figures out where it's actually needed and applies it during your build step.

// What you write
function ProductList({ products, searchTerm }) {
  const filtered = products.filter(p => p.name.includes(searchTerm));
  return <ul>{filtered.map(p => <li key={p.id}>{p.name}</li>)}</ul>;
}

// What the compiler effectively produces (simplified)
function ProductList({ products, searchTerm }) {
  const filtered = useMemo(
    () => products.filter(p => p.name.includes(searchTerm)),
    [products, searchTerm]
  );
  return <ul>{filtered.map(p => <li key={p.id}>{p.name}</li>)}</ul>;
}

You write the simple version. The compiler handles the optimization. This is a genuinely big shift in how React code gets written day to day.

Why This Matters

For years, a big part of "writing performant React" meant knowing exactly when to reach for useMemo, useCallback, and React.memo — and just as importantly, when not to, since overusing them adds overhead without benefit (something worth understanding deeply, not just memorizing rules for). React Compiler removes a huge chunk of that decision-making from your daily workflow. You write straightforward component code, and the compiler figures out the optimization boundaries for you, generally more consistently than most developers would by hand.

This lowers the barrier significantly for newer developers — you can focus on what the component actually does, rather than also having to reason about referential stability and shallow prop comparisons on every component you write.

So Is Manual Memoization Dead?

Not entirely, and here's why it's still worth understanding:

The compiler doesn't cover every case yet. Custom hooks with complex external dependencies, some third-party library integrations, and edge cases the compiler's static analysis can't confidently reason about may still need manual attention.

Understanding why memoization helps makes debugging easier. When something doesn't optimize the way you expect, knowing the underlying mechanics — what actually triggers a re-render, how shallow comparison works — lets you diagnose the issue instead of just guessing.

Not every codebase has adopted it yet. Plenty of production apps are still running without React Compiler, especially larger, older codebases where adopting a new build-time tool takes deliberate migration effort. If you're working on one of these, the manual APIs are still exactly as relevant as before.

Adopting It in an Existing Project

npm install babel-plugin-react-compiler

// babel.config.js
module.exports = {
  plugins: ["babel-plugin-react-compiler"],
};

The compiler is designed to be adopted incrementally — you don't need to rewrite your whole codebase at once. It analyzes your existing components and applies optimizations where it's confident doing so is safe, without requiring you to change how you write components.

What This Means for Learning React in 2026

If you're newer to React, this is genuinely good news: you can focus your energy on understanding component structure, hooks, and data flow, without needing to simultaneously master manual performance optimization from day one. That said, I'd still recommend understanding what the compiler is doing under the hood — reading about how useMemo and React.memo work conceptually will make you a stronger developer even if you rarely write them by hand going forward, the same way understanding how a car engine works makes you a better driver even if you never plan to fix one yourself.

Final Thoughts

React Compiler is one of the more meaningful shifts in how React gets written in years — less boilerplate, fewer performance footguns, and a lower barrier to entry for people learning React right now. It doesn't make performance knowledge irrelevant, but it does change where that knowledge matters most: less in your daily component code, more in the rare cases where the compiler needs a hand, or when you're maintaining a codebase that hasn't adopted it yet.

Muhammad Farhan is a Frontend Developer specializing in React.js and Tailwind CSS, based in Dera Ismail Khan, Pakistan. Portfolio: Muhammad Farhan

How to Build Your First React Component (Step-by-Step)

Fri, 07 Aug 2026 05:00:00 +0000

Introduction

Your first React component doesn't need to be complicated. In fact, the biggest mistake beginners make is trying to build something too ambitious right away and getting stuck on concepts they haven't learned yet.

We're building something practical and genuinely useful: a reusable Testimonial Card component — the kind of thing that shows up in real portfolios and client projects constantly.

Step 1: Understand What a Component Actually Is

A React component is just a JavaScript function that returns some JSX (HTML-like syntax). That's the whole concept.

function Greeting() {
  return <h1>Hello, world!</h1>;
}

You use it like an HTML tag:

<Greeting />

Step 2: Build the Static Version First

Before adding any dynamic data, get the layout right with hardcoded content:

function TestimonialCard() {
  return (
    <div className="bg-slate-800 rounded-2xl p-6 max-w-sm shadow-lg">
      <p className="text-slate-300 mb-4">
        "This developer delivered exactly what we needed, on time and with great communication."
      </p>
      <div className="flex items-center gap-3">
        <div className="w-10 h-10 rounded-full bg-blue-500"></div>
        <div>
          <p className="text-white font-semibold">Sarah Ahmed</p>
          <p className="text-slate-400 text-sm">Product Manager</p>
        </div>
      </div>
    </div>
  );
}

Notice: no state, no props, nothing dynamic. Just structure and styling. This is genuinely how you should approach every new component — get the static layout right first.

Step 3: Make It Reusable with Props

Right now this card only shows one testimonial. Props let you reuse the same component with different data:

function TestimonialCard({ quote, name, role }) {
  return (
    <div className="bg-slate-800 rounded-2xl p-6 max-w-sm shadow-lg">
      <p className="text-slate-300 mb-4">"{quote}"</p>
      <div className="flex items-center gap-3">
        <div className="w-10 h-10 rounded-full bg-blue-500"></div>
        <div>
          <p className="text-white font-semibold">{name}</p>
          <p className="text-slate-400 text-sm">{role}</p>
        </div>
      </div>
    </div>
  );
}

Now you use it like this:

<TestimonialCard
  quote="This developer delivered exactly what we needed, on time."
  name="Sarah Ahmed"
  role="Product Manager"
/>

{ quote, name, role } is destructuring the props object — same as writing props.quote, props.name, props.role, just cleaner.

Step 4: Render a List of Them

In a real project, you'd map over an array of testimonial data:

const testimonials = [
  { quote: "Great work, fast turnaround.", name: "Ali Raza", role: "Founder" },
  { quote: "Clean code and clear communication.", name: "Sarah Ahmed", role: "PM" },
  { quote: "Would hire again without hesitation.", name: "James Lee", role: "CTO" },
];

function TestimonialGrid() {
  return (
    <div className="grid md:grid-cols-3 gap-6 p-6">
      {testimonials.map((item, index) => (
        <TestimonialCard key={index} {...item} />
      ))}
    </div>
  );
}

{...item} spreads the object properties as individual props automatically — a common React pattern once you're comfortable with the basics.

Important: the key prop is required whenever you render a list. React uses it to track which items changed. In a real project, use a unique ID from your data rather than the array index if possible.

Step 5: Add a Bit of Interactivity (Optional)

Want to show a "Read more" toggle for long quotes? That's where useState comes in — covered in detail in Article 5, but here's the quick version:

function TestimonialCard({ quote, name, role }) {
  const [expanded, setExpanded] = useState(false);

  return (
    <div className="bg-slate-800 rounded-2xl p-6 max-w-sm shadow-lg">
      <p className={`text-slate-300 mb-4 ${!expanded && "line-clamp-2"}`}>
        "{quote}"
      </p>
      <button onClick={() => setExpanded(!expanded)} className="text-blue-400 text-sm mb-4">
        {expanded ? "Show less" : "Read more"}
      </button>
      {/* rest of the card */}
    </div>
  );
}

Common Beginner Mistakes

Trying to add state and interactivity before the static layout is right. Get the structure and styling working first — add logic after.
Forgetting the key prop when rendering lists. React will warn you in the console — don't ignore that warning.
Not destructuring props. Writing props.quote everywhere instead of destructuring is more typing and harder to read.
Building one giant component instead of small, focused ones. If a component is doing three different jobs, split it into three components.

Final Thoughts

Building your first real component is less about React "magic" and more about breaking a UI down into small, reusable pieces — static first, then props, then interactivity if needed. Rebuild this same pattern (static → props → list → interactivity) for your next few components and it'll start feeling automatic.

Muhammad Farhan is a Frontend Developer specializing in React.js and Tailwind CSS, based in Dera Ismail Khan, Pakistan.
Portfolio: Muhammad Farhan

Understanding React Hooks: useState and useEffect Explained Simply

Tue, 28 Jul 2026 05:00:00 +0000

Introduction

Hooks confused me for longer than I'd like to admit. Not the syntax — the syntax is simple. What confused me was when to use useEffect versus just writing normal logic in my component.

If you're at that stage right now, this article is for you. We're keeping this practical — real examples, real mistakes, no theory-heavy explanations of React's internal fiber architecture.

useState: Giving Your Component Memory

Without state, a component renders once and forgets everything. useState lets a component remember values between renders — and re-render automatically when that value changes.

import { useState } from 'react';

function Counter() {
  const [count, setCount] = useState(0);

  return (
    <div>
      <p>Count: {count}</p>
      <button onClick={() => setCount(count + 1)}>Increase</button>
    </div>
  );
}

count is the current value. setCount is the function you call to update it. Calling setCount tells React "re-render this component with the new value" — you never update count directly.

Common Mistake: Updating State Based on Old State

This looks fine but can cause bugs:

setCount(count + 1);
setCount(count + 1); // still only adds 1, not 2!

Fix it with the function form:

setCount(prev => prev + 1);
setCount(prev => prev + 1); // now correctly adds 2

This matters more than it seems — always use the function form when your new state depends on the previous state.

useEffect: Running Code at the Right Time

useEffect lets you run code in response to a component rendering, or a specific value changing — things like fetching data, updating the page title, or setting up an event listener.

import { useState, useEffect } from 'react';

function UserProfile({ userId }) {
  const [user, setUser] = useState(null);

  useEffect(() => {
    fetch(`https://api.example.com/users/${userId}`)
      .then(res => res.json())
      .then(data => setUser(data));
  }, [userId]);

  if (!user) return <p>Loading...</p>;
  return <h2>{user.name}</h2>;
}

The array at the end — [userId] — is the dependency array. It tells React "only re-run this effect when userId changes."

The Three Dependency Array Patterns

useEffect(() => { /* code */ });          // runs after EVERY render
useEffect(() => { /* code */ }, []);       // runs ONCE, after the first render
useEffect(() => { /* code */ }, [userId]); // runs when userId changes

Beginners almost always want one of the last two. An empty array [] is for one-time setup (like fetching initial data). A populated array is for "re-run this when X changes."

Cleaning Up After Effects

Some effects need cleanup — like removing an event listener when the component unmounts:

useEffect(() => {
  const handleResize = () => console.log(window.innerWidth);
  window.addEventListener('resize', handleResize);

  return () => {
    window.removeEventListener('resize', handleResize);
  };
}, []);

The function you return inside useEffect is the cleanup function. React calls it automatically before the component unmounts, or before the effect runs again.

Common Beginner Mistakes

Forgetting the dependency array entirely. This causes the effect to run after every single render, often triggering infinite fetch loops.
Missing a dependency. If your effect uses a variable from outside it, add it to the array — ESLint's react-hooks/exhaustive-deps rule will warn you about this.
Putting everything in useEffect. Not all logic needs to live in an effect. If you're just calculating a value from props or state, do it directly in the component body — no hook needed.

Final Thoughts

useState gives your component memory. useEffect lets it react to changes and the outside world (APIs, timers, event listeners). Once you separate those two jobs clearly in your head, hooks stop feeling mysterious.

Try rebuilding a small feature — a search box with an API call, for example — using exactly these two hooks. That's usually the exercise that makes it click.

Muhammad Farhan is a Frontend Developer specializing in React.js and Tailwind CSS, based in Dera Ismail Khan, Pakistan.
Portfolio: muhammad-farhan-dev.github.io/muhammadfarhan.dev

Hire Me: Muhammad Farhan — Frontend Developer Available for Remote Work

Thu, 23 Jul 2026 09:31:37 +0000

Hi, I'm Muhammad Farhan

I'm a frontend developer based in Dera Ismail Khan, Pakistan, and I build clean, modern, fast-loading websites using React.js, Tailwind CSS, and WordPress. If you need a website built, a design turned into working code, or an existing site improved, I'd genuinely like to help — and I'm available to start right away.

What I Actually Do

I specialize in:

React.js — component-based, interactive web apps built to scale
Tailwind CSS — clean, modern, fully responsive UI, my go-to styling approach
HTML5 & CSS3 — solid, semantic, accessible markup underneath every project
JavaScript (ES6+) — smooth interactivity, no clunky or broken UI
Bootstrap — for projects that need it, including maintaining older sites
WordPress — theme customization, blog setup, and full client websites, including custom frontend features layered on top

Real Work, Not Just Promises

UX Gazette — a professional blog website I built for a real client on WordPress, live at uxgazette.com
Personal Portfolio — my own site, showcasing my design and development work
Multiple additional projects across business landing pages, animated websites, and UI design work

I don't just talk about being able to build things — every skill listed above has a real, live, shipped project behind it that you can actually visit and click through.

Why Work With Me

I communicate clearly and respond fast. No chasing me for updates — I keep you informed without being asked.
I care about clean, maintainable code, not just something that looks right on the surface and breaks the moment it needs a change.
I'm affordable for the quality I deliver, especially compared to larger agencies, while still meeting professional standards.
I'm available now — for a single project, an ongoing freelance arrangement, or a part-time/remote role.

What I Can Help You With

Building a new website from scratch (business site, portfolio, landing page)
Converting a Figma or Adobe XD design into a fully working, responsive website
Fixing bugs or improving performance on an existing site
Customizing or maintaining a WordPress site
Building custom tools, dashboards, or interactive features with React

Let's Talk About Your Project

If you have a project in mind — big or small — I'd love to hear about it. Reach out directly using any of the details below, and I'll get back to you quickly.

Email: Emails are not allowed
Phone / WhatsApp: +92 335-4051272
Portfolio: Click Here
GitHub: Click Here
Behance: Click Here
Instagram: Click Here
X (Twitter): Click Here
WhatsApp Channel: Click Here

Feel free to message me directly on WhatsApp for the fastest response — I usually reply within a few hours.

Muhammad Farhan — Frontend Developer specializing in React.js and Tailwind CSS, based in Dera Ismail Khan, Pakistan.

15 Free Frontend Tools Every Developer Should Know in 2026

Tue, 14 Jul 2026 06:38:30 +0000

Introduction

When I started learning frontend development, I thought I needed expensive software to build things that looked "professional." Turns out, that's completely false.

Some of the best frontend tools out there are free — and a lot of developers, even experienced ones, don't know half of them exist. Whether you're picking colors, generating CSS animations, testing responsiveness, or just trying to find the right icon, there's a free tool for almost everything.

In this post, I'm sharing 15 tools I personally use (or have used) while building real projects — from client websites to personal portfolios. No fluff, no "100 tools you'll never open" lists. Just the ones that actually save time.

Let's get into it.

1. Design & Color Tools

Good design starts with good colors and layout inspiration. These tools take the guesswork out of it.

Coolors

Coolors is the fastest way to generate a color palette. Hit the spacebar and it keeps generating combinations until you find one you like. You can lock colors you love and regenerate the rest.

Why beginners love it: No design theory needed — just pick what looks good.
🔗 coolors.co

Adobe Color

More advanced than Coolors, this lets you build palettes based on color theory rules (complementary, triadic, monochromatic, etc.) and even extract a palette from an image.

Why it's useful: Great when you want a palette that matches a client's brand photo or logo.
🔗 color.adobe.com

2. CSS Generators (Stop Writing Gradients by Hand)

CSS Gradient

Pick colors, choose the direction, and copy the ready-made CSS. Simple, fast, and works for linear and radial gradients.
🔗 cssgradient.io

Neumorphism.io

If you want that soft, "pressed-in" neumorphic UI style, this generator gives you the exact box-shadow code — adjustable by distance, blur, and intensity, with light/dark background support.
🔗 neumorphism.io

Clippy

Need a custom shape (hexagon, arrow, triangle) using clip-path? Clippy lets you drag points visually and copies the CSS for you. No more guessing polygon coordinates.
🔗 bennettfeely.com/clippy

Pro tip: These generators are amazing for learning too — generate the code, then read it and understand why it works. That's how I actually learned box-shadow and clip-path properties.

3. Icons That Don't Look Generic

Lucide Icons

A clean, consistent icon set that works beautifully with React and Tailwind CSS. Lightweight, tree-shakable, and has an official React package (lucide-react).
🔗 lucide.dev

Heroicons

Made by the Tailwind CSS team, so naturally it pairs perfectly with Tailwind projects. Comes in outline and solid styles.
🔗 heroicons.com

Font Awesome (Free Tier)

The classic. Massive icon library, and the free tier alone covers most needs — social icons, UI icons, brand logos.
🔗 fontawesome.com

My pick for React + Tailwind projects: Lucide. It's the one I use across my own builds because it's lightweight and easy to customize with Tailwind classes.

4. Fonts & Typography

Google Fonts

The obvious one, but don't just grab the first font you see. Google Fonts also shows you popularity, styles, and lets you preview your own text before choosing.
🔗 fonts.google.com

Fontjoy

Struggling to pair a heading font with a body font? Fontjoy uses AI to suggest font combinations that actually work together — and you can lock one font and regenerate the other.
🔗 fontjoy.com

5. Online Code Playgrounds

CodePen

Great for quick CSS/JS experiments, sharing snippets, and browsing what other developers are building. Perfect for testing an animation idea before adding it to a real project.
🔗 codepen.io

StackBlitz

A full online IDE that runs actual React, Vue, or Node projects in your browser — no local setup needed. I use this a lot when testing a quick React component idea.
🔗 stackblitz.com

CodeSandbox

Similar to StackBlitz, with strong support for sharing full working React apps and instant deployment previews. Great for collaborating or showing a client a live demo without deploying anywhere.
🔗 codesandbox.io

6. Image Optimization Tools

Heavy images kill website speed — and speed affects both user experience and SEO rankings.

Squoosh

Made by Google. Drag in an image, compare compression formats (WebP, AVIF, JPEG) side by side, and download the optimized version — all in your browser, nothing uploaded to a server.
🔗 squoosh.app

TinyPNG

Bulk compress PNG and JPEG images with barely noticeable quality loss. I run every client project's images through this before deployment.
🔗 tinypng.com

7. Responsive & Accessibility Testing

Responsively App

A free desktop app that shows your website on multiple device sizes at once, side by side, and syncs scrolling and clicks across all of them. Saves so much time compared to resizing your browser manually.
🔗 responsively.app

Chrome DevTools (Lighthouse)

Built right into Chrome. Open DevTools → Lighthouse tab → run an audit. It scores your site on performance, accessibility, best practices, and SEO, and tells you exactly what to fix.

Why this matters for freelancers: Clients love seeing a 90+ Lighthouse score. It's an easy way to prove your work is solid.

WAVE

A free accessibility checker. Paste your URL and it visually flags missing alt text, low contrast, and other accessibility issues directly on the page.
🔗 wave.webaim.org

8. Reference & Learning

MDN Web Docs

The single most reliable source for HTML, CSS, and JavaScript documentation. When in doubt, check MDN before trusting a random blog post (including this one).
🔗 developer.mozilla.org

Can I Use

Before using a newer CSS or JS feature, check browser support here. Saves you from shipping something that breaks in Safari or older browsers.
🔗 caniuse.com

Final Thoughts

You don't need a paid design subscription or premium plugin to build clean, professional websites. The tools above cover almost every stage of frontend work — design, coding, testing, and optimization — and they're all free.

My honest advice as someone who's been learning and building for the past couple of years: don't try to learn all 15 tools at once. Pick 2–3 that solve a problem you're facing right now, use them in your next project, and the rest will come naturally as you build more.

If you found this useful, save it — you'll probably come back to this list more than once.

Written by Muhammad Farhan — Frontend Developer specializing in React.js & Tailwind CSS, based in Dera Ismail Khan, Pakistan.
Portfolio: muhammad-farhan-dev.github.io/muhammadfarhan.dev
GitHub: github.com/muhammad-farhan-dev

I Built a QR Label Designer That Connects Directly to Your Data Tables — Here's How It Works

Wed, 01 Jul 2026 21:00:59 +0000

Ever had to print 200 warehouse bin labels and realized there's no clean way to do it from a web app?

That's what pushed me to build qrlayout-core and qrlayout-ui — two open source npm packages for designing QR label templates and bulk-printing them from React. This post walks through the full workflow with real code.

The Problem

Printing QR labels from a web app usually means one of these:

Generating them one at a time manually
Hardcoding the label layout in your codebase
Exporting a CSV and using a desktop app

None of these scale. And none of them give non-technical users control over the label design.

The Solution: Two Packages, One Pipeline

qrlayout-ui — a drag-and-drop label designer your users can embed directly in your app
qrlayout-core — the headless rendering engine that turns saved templates + data into PNG, PDF, or ZPL

npm install qrlayout-core qrlayout-ui

The workflow looks like this:

Labels Tab   →  Design a template, save it with a title + entity type
Master Table →  Select that saved layout from a dropdown
Table Rows   →  Check the records you want
Export       →  PNG · PDF · ZPL (thermal printer)

The key idea: template and data stay separate. One layout generates labels for hundreds of records. And because each template is tagged to an entity (employee, machine, storage), the master table only shows layouts relevant to it.

Step 1: Define Entity Schemas

You tell the designer what fields each entity has. This powers the live preview — every {{field}} placeholder dropped on the canvas renders with real sample data instantly.

const SAMPLE_SCHEMAS = {
  storage: {
    label: "Storage Master",
    fields: [
      { name: "binCode",     label: "BIN Code" },
      { name: "storageType", label: "Storage Type" },
      { name: "aisle",       label: "Aisle" },
      { name: "rack",        label: "Rack Number" },
    ],
    sampleData: {
      binCode: "BIN-A1-R4", storageType: "Pallet Rack",
      aisle: "Aisle 01",    rack: "R-44"
    }
  },
  // employee and machine follow the same shape
};

Step 2: Mount the Designer in React

qrlayout-ui is framework-agnostic so you mount it with a ref + useEffect. Two things matter most — passing onSave to capture the layout JSON, and calling destroy() on unmount to prevent memory leaks.

useEffect(() => {
  if (!containerRef.current) return;

  designerRef.current = new QRLayoutDesigner({
    element: containerRef.current,
    entitySchemas: SAMPLE_SCHEMAS,
    initialLayout: editingLayout || { ...DEFAULT_NEW_LAYOUT, id: crypto.randomUUID() },
    onSave: (layout) => {
      storage.addLabel(layout);        // persist the layout JSON
      setLabels(storage.getLabels());
      setSubView('list');
    }
  });

  return () => {
    designerRef.current?.destroy();    // always clean up
    designerRef.current = null;
  };
}, [subView, editingLayout]);

When the user clicks Save inside the designer, onSave fires with the complete StickerLayout JSON — name, target entity, dimensions, and all elements. That single JSON object is what flows through the entire rest of the system.

Step 3: The Master Table — Select Rows, Pick Layout, Export

Each master table (Employees, Machines, Storage BINs) filters layouts by targetEntity so users only see relevant templates in the dropdown.

// Only load layouts relevant to this entity
const binLabels = storage.getLabels().filter(l => l.targetEntity === 'storage');

const getSelectedBins = () => bins.filter(b => selectedBinIds.includes(b.id));
const getActiveLayout = () => labels.find(l => l.id === selectedLayoutId);

const handleExportPDF = async () => {
  const layout = getActiveLayout();
  const selected = getSelectedBins();
  if (!layout) return;
  await exportToBatchPDF({
    layout,
    items: selected,
    printer: printer.current,
    baseFilename: 'batch-bin-labels'
  });
};

When rows are selected, the export toolbar appears with three options. Until then the page shows a step-by-step guide so users know what to do.

Step 4: Three Export Formats

// PNG — one file per item
printer.renderToDataURL(layout, item, { format: 'png' })

// PDF — all items in one document
import { exportToPDF } from 'qrlayout-core/pdf';
const pdf = await exportToPDF(layout, items);
pdf.save('labels.pdf');

// ZPL — for Zebra and other thermal printers
const zplCommands = printer.exportToZPL(layout, items);
// In production: send over TCP port 9100 directly to the printer

exportToPDF is a separate optional import to keep the core bundle light. ZPL output is an array of strings — one per label — which you can download as a .txt file or pipe straight to a Zebra printer over TCP.

Try It — Pre-Loaded Demo Data

The live demo seeds everything on first load:

3 layouts — Professional ID Badge, Equipment Asset Tag, Storage Location Label
3 employees — Arjun Mehta, Priya Sharma, Kiran Patel
3 machines — CNC Router X1, Industrial 3D Printer, Hydraulic Press
3 bins — BIN-A1-R1 (Pallet Rack), BIN-A1-R2 (Shelf), BIN-B2-R1 (Cold Storage)

Go to Storage → check all bins → click PDF. Done in 30 seconds.

This is a Frontend Demo — Here's the Production Path

Everything in the demo runs in the browser using localStorage. In a real project you'd swap each layer with a backend equivalent:

Demo	Production
`localStorage` (layouts)	DB table with a `layout_json` column
`localStorage` (bins/machines)	Your existing ERP or database
Client-side filter by `targetEntity`	`WHERE target_entity = 'storage'`
Browser PDF download	Node.js server-side render → stream to client
`.txt` ZPL download	TCP socket → Zebra printer (port 9100)

qrlayout-core has zero browser dependencies — exportToPDF and printer.exportToZPL work identically in Node.js. The full production flow:

React Frontend
  └── qrlayout-ui  →  user designs label → onSave fires layout JSON
  └── POST /api/layouts  →  save to DB

Node.js Backend
  └── GET /api/layouts?entity=storage  →  filtered layouts to frontend
  └── POST /api/labels/print
        ├── fetch layout from DB
        ├── fetch selected records from ERP / DB
        ├── exportToPDF(layout, items)  →  stream PDF to client
        └── printer.exportToZPL(layout, items)  →  TCP → Zebra printer

Links

Happy to answer questions about the implementation in the comments.

I Built a QR Label Designer That Connects Directly to Your Data Tables — Here's How It Works

Wed, 01 Jul 2026 17:06:32 +0000

Ever had to print 200 warehouse bin labels and realized there's no clean way to do it from a web app?

The Problem

Printing QR labels from a web app usually means one of these:

Generating them one at a time manually
Hardcoding the label layout in your codebase
Exporting a CSV and using a desktop app

None of these scale. And none of them give non-technical users control over the label design.

The Solution: Two Packages, One Pipeline

qrlayout-ui — a drag-and-drop label designer your users can embed directly in your app
qrlayout-core — the headless rendering engine that turns saved templates + data into PNG, PDF, or ZPL

npm install qrlayout-core qrlayout-ui

The workflow looks like this:

Labels Tab   →  Design a template, save it with a title + entity type
Master Table →  Select that saved layout from a dropdown
Table Rows   →  Check the records you want
Export       →  PNG · PDF · ZPL (thermal printer)

Step 1: Define Entity Schemas

You tell the designer what fields each entity has. This powers the live preview — every {{field}} placeholder dropped on the canvas renders with real sample data instantly.

const SAMPLE_SCHEMAS = {
  storage: {
    label: "Storage Master",
    fields: [
      { name: "binCode",     label: "BIN Code" },
      { name: "storageType", label: "Storage Type" },
      { name: "aisle",       label: "Aisle" },
      { name: "rack",        label: "Rack Number" },
    ],
    sampleData: {
      binCode: "BIN-A1-R4", storageType: "Pallet Rack",
      aisle: "Aisle 01",    rack: "R-44"
    }
  },
  // employee and machine follow the same shape
};

Step 2: Mount the Designer in React

useEffect(() => {
  if (!containerRef.current) return;

  designerRef.current = new QRLayoutDesigner({
    element: containerRef.current,
    entitySchemas: SAMPLE_SCHEMAS,
    initialLayout: editingLayout || { ...DEFAULT_NEW_LAYOUT, id: crypto.randomUUID() },
    onSave: (layout) => {
      storage.addLabel(layout);        // persist the layout JSON
      setLabels(storage.getLabels());
      setSubView('list');
    }
  });

  return () => {
    designerRef.current?.destroy();    // always clean up
    designerRef.current = null;
  };
}, [subView, editingLayout]);

Step 3: The Master Table — Select Rows, Pick Layout, Export

Each master table (Employees, Machines, Storage BINs) filters layouts by targetEntity so users only see relevant templates in the dropdown.

// Only load layouts relevant to this entity
const binLabels = storage.getLabels().filter(l => l.targetEntity === 'storage');

const getSelectedBins = () => bins.filter(b => selectedBinIds.includes(b.id));
const getActiveLayout = () => labels.find(l => l.id === selectedLayoutId);

const handleExportPDF = async () => {
  const layout = getActiveLayout();
  const selected = getSelectedBins();
  if (!layout) return;
  await exportToBatchPDF({
    layout,
    items: selected,
    printer: printer.current,
    baseFilename: 'batch-bin-labels'
  });
};

When rows are selected, the export toolbar appears with three options. Until then the page shows a step-by-step guide so users know what to do.

Step 4: Three Export Formats

// PNG — one file per item
printer.renderToDataURL(layout, item, { format: 'png' })

// PDF — all items in one document
import { exportToPDF } from 'qrlayout-core/pdf';
const pdf = await exportToPDF(layout, items);
pdf.save('labels.pdf');

// ZPL — for Zebra and other thermal printers
const zplCommands = printer.exportToZPL(layout, items);
// In production: send over TCP port 9100 directly to the printer

Try It — Pre-Loaded Demo Data

The live demo seeds everything on first load:

3 layouts — Professional ID Badge, Equipment Asset Tag, Storage Location Label
3 employees — Arjun Mehta, Priya Sharma, Kiran Patel
3 machines — CNC Router X1, Industrial 3D Printer, Hydraulic Press
3 bins — BIN-A1-R1 (Pallet Rack), BIN-A1-R2 (Shelf), BIN-B2-R1 (Cold Storage)

Go to Storage → check all bins → click PDF. Done in 30 seconds.

This is a Frontend Demo — Here's the Production Path

Everything in the demo runs in the browser using localStorage. In a real project you'd swap each layer with a backend equivalent:

Demo	Production
`localStorage` (layouts)	DB table with a `layout_json` column
`localStorage` (bins/machines)	Your existing ERP or database
Client-side filter by `targetEntity`	`WHERE target_entity = 'storage'`
Browser PDF download	Node.js server-side render → stream to client
`.txt` ZPL download	TCP socket → Zebra printer (port 9100)

qrlayout-core has zero browser dependencies — exportToPDF and printer.exportToZPL work identically in Node.js. The full production flow:

React Frontend
  └── qrlayout-ui  →  user designs label → onSave fires layout JSON
  └── POST /api/layouts  →  save to DB

Node.js Backend
  └── GET /api/layouts?entity=storage  →  filtered layouts to frontend
  └── POST /api/labels/print
        ├── fetch layout from DB
        ├── fetch selected records from ERP / DB
        ├── exportToPDF(layout, items)  →  stream PDF to client
        └── printer.exportToZPL(layout, items)  →  TCP → Zebra printer

Links

Happy to answer questions about the implementation in the comments.

Stop Juggling Browser Tabs: Why I Built a Desktop App for JSON, Regex, and Cron

Tue, 09 Jun 2026 06:05:41 +0000

TL;DR: I got tired of switching between a dozen browser tabs for developer tools. So I built Smart Utils Desktop – a native app that handles JSON formatting, regex testing, and cron scheduling. All offline. All private. All in one place.
The Problem Every Developer Knows

Let me describe a typical Tuesday.

I'm debugging an API integration. The response comes back as minified JSON – one massive, unreadable line. I open a browser tab, search for "JSON formatter," click the first result, paste my data, and click Format.

Then the ad loads. Then the popup asks me to sign up. Then I close it and try the next site.

Twenty minutes later, I have my formatted JSON. But now I need to test a regex pattern for email validation. Another tab. Another search. More ads. More popups.

Then I need a cron expression for a daily backup. You guessed it – another tab.

By the end of the day, I have fifteen browser tabs open. My laptop fan is screaming. And somewhere out there, a dozen different websites have stored my API keys, my regex patterns, and my data.

There had to be a better way.
The Breaking Point

The moment that pushed me over the edge happened last winter.

I was working on a JSON file that was about 85MB – not huge by modern standards, but too big for most browser-based tools. I tried five different online JSON formatters. Every single one either:

Froze my browser tab

Showed an error message about file size

Asked me to pay for a "pro" plan

One site actually uploaded my data to their server without telling me. I found out because their privacy policy (which I had to dig for) mentioned "data may be stored for analytics purposes."

That was it.

I closed all my tabs, opened my code editor, and started building the tool I actually wanted to use.
What I Built: Smart Utils Desktop

Smart Utils Desktop is a native application that combines the most common developer utilities into one clean, fast, offline-first app.
JSON Studio

This is the heart of the app. You can:

Format – Turn minified JSON into readable, indented structure

Minify – Compress JSON for production use

Validate – Catch syntax errors instantly

Tree View – Visualize nested data and copy any JSONPath

Generate Schema – Create JSON Schema from any document

Generate Code – Produce model classes for TypeScript, Java, Python, Go, Kotlin, and C#

And unlike web-based tools, you can open and save files directly from your hard drive. The app handles JSON files up to 100MB without breaking a sweat.
Regex Builder

Regex is powerful, but testing it can be painful. Smart Utils gives you:

Live highlighting – See matches as you type

Pattern library – One-click templates for email, URL, UUID, numbers, words, whitespace

Flag controls – Toggle global, case-insensitive, multiline, and dotall modes

Match count – Instantly see how many matches were found

Save patterns – Keep your frequently-used expressions

Cron Builder

Cron syntax is easy to forget. This tool makes it visual:

Field-by-field editor – Select minute, hour, day, month, weekday

Preset schedules – Every minute, hourly, daily at 9am, weekdays, monthly

Plain English – "At 09:00 on every day-of-week from Monday through Friday"

One-click copy – Grab the expression and paste it into your crontab

CSV Converter (Desktop Exclusive)

Business people love CSV. Developers love JSON. This feature bridges the gap:

JSON to CSV – Convert any JSON array to CSV format

CSV to JSON – Import CSV files back to JSON for editing

Field mapping – Select exactly which fields to export

Delimiter options – Comma, semicolon, tab, or pipe

Why Desktop Instead of Web?

This is the question I get asked most. Here's my honest answer:
AspectWeb ToolSmart Utils Desktop
PrivacyYour data goes to their serverYour data stays on your machine
InternetRequiredWorks offline
Large filesUsually failsHandles 100MB+
AdsEverywhereNone
File accessCan't save locallyOpen and save directly
SpeedDepends on networkInstant

I'm not saying web tools are bad. They're great for quick, one-off tasks. But for daily work? I want something that's always there, always fast, and always private.
The Technical Stack

If you're curious about how it's built:

Frontend: React 19 + Vite

Desktop framework: Electron (same as VS Code, Slack, and Discord)

Styling: Vanilla CSS with dark/light themes

CSV processing: PapaParse

Packaging: electron-builder

The entire app is about 80MB – large enough to be feature-rich, small enough to download in seconds.
What's Next?

I'm actively developing Smart Utils. Here's what's coming:

YAML support – Format and validate YAML files

JWT decoder – Inspect and verify JSON Web Tokens

Base64 tools – Encode and decode

SQL formatter – Pretty-print SQL queries

More code generators – Add Ruby, PHP, Swift support

Smart Utils Desktop is available for macOS, Windows, and Linux.

Full license: $1 one-time payment

No subscription: Pay once, use forever

Download Smart Utils Desktop →

The Bottom Line

I built Smart Utils because I needed it. Every day, I use it for JSON formatting, regex testing, and cron scheduling. It saves me time, protects my privacy, and keeps my workflow smooth.

If you're tired of juggling browser tabs and worrying about where your data is going, give it a try. The free trial costs nothing but a few minutes of your time.

Your tools should work for you – not against you.

I built my first Chrome extension because editing localStorage was annoying

Wed, 03 Jun 2026 22:23:18 +0000

I finally published my first Chrome extension.

It is called DataSidekick, and I built it because I got tired of fighting DevTools every time I needed to inspect or edit localStorage and sessionStorage.

Also, yes, I paid the legendary $5 Chrome Web Store developer fee, so emotionally I had to ship something. Otherwise, it would have been the worst investment portfolio of my life.

What is DataSidekick?

DataSidekick is a Chrome extension that opens as a side panel and helps developers work with browser storage in a cleaner way.

Instead of digging through DevTools and editing raw strings, you get a focused interface for:

viewing localStorage
viewing sessionStorage
searching by key or value
editing simple values inline
editing JSON visually
importing data from JSON
exporting data to JSON
hiding noisy keys
requesting access per site/origin

You can check it out here:

https://datasidekick.site

Why I built it

Browser storage is simple until it is not.

A lot of apps store useful state in localStorage, but the default developer experience is still pretty rough:

{"user":{"name":"Rodrigo","settings":{"theme":"dark"}}}

Technically readable? Sure.

Pleasant to edit? Absolutely not.

I wanted something closer to a small developer cockpit: open the panel, find the key, inspect the value, edit it safely, and move on.

The feature I cared about most: visual JSON editing

The main idea was simple:

If a value is valid JSON, don't treat it like a random string.

So instead of this:

{"a":"b","settings":{"theme":"dark"}}

DataSidekick displays structured JSON in a more readable way, so it becomes easier to inspect and edit nested values.

That was the first “okay, this is actually useful” moment.

Chrome permissions were the real boss fight

The extension needs to read and edit storage from the current page. That means permissions matter.

At first, I had an unnecessary permission in the manifest and the Chrome Web Store rejected the extension.

Fair enough. My bad.

The final approach is more intentional:

no unnecessary downloads permission
site access is requested when needed
the user sees when access is required
data stays local in the browser

For a tool that touches browser storage, I think this transparency is important.

Exporting without the downloads permission

One small lesson: exporting a JSON file does not necessarily require the Chrome downloads permission.

This is enough for my use case:

const blob = new Blob([JSON.stringify(payload, null, 2)], {
  type: "application/json"
});

const url = URL.createObjectURL(blob);

const a = document.createElement("a");
a.href = url;
a.download = "datasidekick-export.json";
a.click();

URL.revokeObjectURL(url);

Since I was not using chrome.downloads.download(), the permission was unnecessary.

Chrome Web Store noticed. Chrome Web Store was right.

Painful, but useful.

Current features

The first public version includes:

Chrome Side Panel UI
localStorage and sessionStorage support
visual JSON editor
key/value search
import/export JSON
per-site access flow
hidden keys
noisy key filtering
favorites
dark/light mode
font size controls
playground on the website

The playground

I also added a playground to the site so people can understand the idea before installing anything.

That was important because browser storage tools can feel a bit sensitive. I wanted people to see what the extension does before giving it access to a page.

Try it here:

https://datasidekick.site

What I learned

A few things I took away from this first release:

Small dev tools are still worth building.
Chrome extension permissions deserve real attention.
A simple UX decision can matter more than a complex feature.
Shipping to a store is very different from “it works locally”.
Paying $5 makes you emotionally committed.

What's next?

This is my first Chrome extension, but definitely not the last.

Some ideas for future versions:

IndexedDB support
better diff view
undo/redo
schema validation
storage history
better JSON editing interactions

For now, I am happy it is live.

If you work with localStorage or sessionStorage often, I would love your feedback:

https://datasidekick.site

Or plugin link: DataSideKick

Built by a developer who just wanted to stop editing JSON like a caveman.

Stop Pasting JWTs Into Random Websites. Here's What I Built Instead.

Tue, 02 Jun 2026 06:43:46 +0000

By Abu Sufyan · Lead Systems Architect, WebToolkit Pro

Every week, thousands of developers do something they know they shouldn't.

They open a new browser tab, navigate to some third-party JWT decoder, and paste a live production token directly into it.

That token probably contains a user ID. Maybe a role claim. Maybe an internal service identifier that maps to something sensitive in your infrastructure. And it just left your browser.

I know, because I used to do it too.

The Incident That Made Me Stop

In late 2024, I was debugging an auth issue on a client's Node.js API — a financial services platform. Standard stuff: the access token wasn't refreshing correctly and I needed to inspect the payload quickly to verify the exp claim.

I instinctively opened a well-known JWT decoder site and pasted the token.

Then I stopped.

I was working in a production environment. That token belonged to a real user — a client of theirs. It contained a sub (subject) claim with a UUID that mapped directly to their user database. It contained an iat and exp. And most critically, it contained a roles claim: ["admin", "finance_read"].

I had just sent a production admin token to a third-party server I knew nothing about.

The site claimed it was "client-side only." But I couldn't verify that. There was no open-source repo I could inspect. No audit trail. No CSP headers I could check. Just a text box and a promise.

That afternoon, I filed an internal incident report and started building a replacement.

What Makes a JWT Decoder Dangerous

Before I get to what I built, it's worth understanding exactly why this matters technically — not just philosophically.

A JWT has three parts: header, payload, and signature. The first two are just Base64url-encoded JSON. Decoding them requires zero network traffic. It's pure string manipulation you can do in two lines of JavaScript:

const [header, payload] = token.split('.');
const decoded = JSON.parse(atob(payload.replace(/-/g, '+').replace(/_/g, '/')));

That's it. There is no cryptographic reason a JWT decoder needs to contact any server whatsoever.

And yet, when you paste a token into most online decoders, your token travels over the network to a server. That server may or may not be logging requests. It may be behind a CDN that caches POST bodies. It may be owned by a company whose threat model you have no visibility into.

The attack surface is real:

Session hijacking if the token is still valid and the attacker can replay it against your API
Claim exposure — user IDs, email addresses, role names, tenant identifiers
Infrastructure mapping — the iss (issuer) claim often reveals internal service URLs or identity provider endpoints
Algorithm fingerprinting — the alg header tells an attacker exactly what signing algorithm you're using, useful for crafting exploit attempts

The Architecture: Zero-Knowledge Client-Side Decoding

What I built — the Offline JWT Decoder at WebToolkit Pro — operates on a simple constraint: nothing ever leaves the browser tab.

Here's the actual execution model:

User pastes token → Browser JS splits on '.'
                  → atob() decodes header + payload
                  → JSON.parse() reconstructs the object
                  → Rendered directly into DOM

No fetch(). No XMLHttpRequest(). No WebSocket. No Service Worker relay.

To verify this yourself: open DevTools → Network tab → paste a token → watch. Zero outbound requests. The network panel stays empty.

The implementation uses the Web Crypto API for signature verification — which also runs entirely in the browser sandbox. There are no API keys, no backend, no telemetry. The Content Security Policy on the page blocks outbound requests at the browser level, so even if a malicious script injection somehow occurred, it couldn't exfiltrate the token.

Beyond Decoding: The Signature Verification Problem

Most online JWT decoders only decode. They don't verify.

Decoding tells you what's inside the token. Verification tells you whether to trust it.

The difference matters enormously in debugging scenarios. If you're diagnosing an auth failure, you need to know:

Is the token malformed? (decoding fails)
Is it expired? (check exp vs current timestamp)
Is the signature valid against the expected public key? (actual cryptographic verification)

Point 3 is where most tools fall apart. They skip it entirely, leaving you with no way to confirm whether the token was legitimately issued or tampered with.

The JWT Debugger & Inspector I built handles all three. You can paste your JWKS (JSON Web Key Set) endpoint URL or paste the raw public key directly, and the tool performs RS256/ES256 signature verification locally using window.crypto.subtle.verify() — the same Web Crypto primitive your browser uses for HTTPS.

// What's happening under the hood
const key = await crypto.subtle.importKey(
  'jwk',
  jwkPublicKey,
  { name: 'RSASSA-PKCS1-v1_5', hash: 'SHA-256' },
  false,
  ['verify']
);

const isValid = await crypto.subtle.verify(
  'RSASSA-PKCS1-v1_5',
  key,
  signature,
  data
);

No server. No SDK. Pure browser cryptography.

The `alg: none` Attack — Why Your Decoder Needs to Flag This

While building this, I added one feature that I think every JWT tool should have: automatic detection of the alg: none exploit vector.

Here's the attack. Some JWT libraries — particularly older versions — accept tokens where the algorithm is set to none and the signature is empty. An attacker who knows this can forge a token with any payload they want:

// Header
{
  "alg": "none",
  "typ": "JWT"
}
// Payload
{
  "sub": "1234567890",
  "roles": ["admin"],
  "iat": 1516239022
}
// Signature: empty string

This gets concatenated as base64(header).base64(payload). — note the trailing dot with no signature.

The decoder flags this immediately with a warning: ⚠ Algorithm "none" detected. This token carries no cryptographic integrity guarantee. Reject in production.

It's a small thing, but it's the kind of context-aware output you only get from a tool built by someone who actually works with these tokens in production.

What I Learned Building Privacy-First Tools

This JWT decoder is one of 150+ tools I've built at WebToolkit Pro. Every single one follows the same constraint: your data never leaves your browser.

Password generator. Hash generator. Base64 encoder. Regex tester. JSON formatter. AES encryption tool. All of them execute entirely client-side.

Building this way taught me a few things:

WebAssembly changed what's possible. Operations that used to require a server — like Argon2 password hashing, which is deliberately memory-intensive — can now run in the browser via WASM. The Argon2 Hasher generates production-grade password hashes locally in under a second.

Web Workers are underused. For tools that process large inputs (the JSON formatter handles payloads up to 50MB), moving the parsing off the main thread via Web Workers keeps the UI responsive. No spinners, no freezes.

The hardest part isn't the crypto — it's the UX. Security tools have a reputation for being hostile to use. I spent more time on the output formatting and error messaging than on the underlying algorithms. A tool that correctly identifies an exp claim mismatch but displays it as a raw timestamp integer has failed its user.

Try It Yourself

If you're debugging JWTs today, open DevTools first. Network tab, record. Then go to wtkpro.site/tools/jwt-decoder and paste your token.

Watch the network panel stay silent.

That silence is the feature.

How Does Duolingo Monetize? I Decompiled the Android App (v6.79.5)

Fri, 29 May 2026 03:14:43 +0000

I wanted to know how Duolingo makes money on Android -- ads vs Super subscription, which SDKs they use, and how aggressive the free tier is. So I decompiled Duolingo 6.79.5 (164 MB APK, 11 DEX files, 242 activities).

TL;DR

IronSource mediation sits at the center -- Unity Ads, Vungle, Moloco, AdMob, Facebook, and Pangle all plug in around it
Facebook Audience Network ships as a 5 MB hidden DEX in assets (same trick as CamScanner)
7+ ad networks for free users; Google Play Billing for Super/Plus (no RevenueCat found)
Kotlin + Jetpack Compose for the main app; Unity for some game modules (chess, etc.)
Staging APIs (android-api-stage, goals-api-stage-*) are hardcoded in the production build
Adjust + Sentry (+ Firebase) for attribution and crashes

How Duolingo Makes Money

Subscriptions (Super / Plus)

Duolingo uses Google Play Billing directly -- ProxyBillingActivity, PlusPurchaseFlowActivity, strings for gems and family plans. Deep links hit duolingo.com/settings/super.

I did not find RevenueCat or Superwall in the DEX. Subscription logic appears first-party on top of Google's billing library.

Ads (free tier)

Free users hit a mediation-heavy stack:

Network	Role
IronSource	Mediation hub (most SDK surface area)
Unity Ads	Mediated demand + game ad units
Google AdMob	Google demand, MRAID native templates
Facebook AN	Hidden `audience_network.dex`
Pangle (TikTok)	Rewarded, interstitial, app open
Vungle	Video
Moloco	Programmatic / MRAID / VAST

Duolingo-owned ad screens include CustomNativeAdActivity, FullscreenNetworkNativeAdActivity, and PlusPromoVideoActivity -- ads show up at session end and league flows, not random webviews.

The hidden Facebook DEX (again)

assets/audience_network.dex  ~5 MB

Meta's SDK is not fully embedded in the main multidex load. It is loaded from assets when needed -- a common pattern to protect cold start on huge apps.

Tech Stack (what they built with)

Layer	Choice
UI	Kotlin + Jetpack Compose (thousands of references)
Games	Unity (`UnityActivity`, chess promo assets)
Network	OkHttp, Retrofit
Media	ExoPlayer, Lottie, Rive
Attribution	Adjust
Crashes	Sentry (`duolingo-sentry.sentry.io`) + Firebase
Support	Zendesk

Min SDK 29 -- they have dropped pre-Android 10 devices.

Staging servers in production

Same class of mistake as other big apps:

android-api-stage.duolingo.com
goals-api-stage.duolingo.com (+ stage-2, stage-3)
infra-edge-gateway-stage-cf.duolingo.com

Useful if you are researching API behavior; risky if those hosts expose looser auth.

Duolingo vs CamScanner (quick compare)

I decompiled CamScanner earlier:

	CamScanner	Duolingo
Mediation lead	AdMob + PubMatic bidding	IronSource + Unity
UI	Native + Flutter	Compose + Unity games
Ad networks	6	7+
Hidden Meta DEX	Yes	Yes

Education apps and utility apps converge on the same playbook: many networks, one mediator, lazy-load Meta.

What I left out of this post

The full report includes 60+ first-party API hosts, complete permission breakdown, schools/DET endpoints, and module-level Activity mapping. This post is the highlights.

I run AppXray -- send any Google Play link, get a full reverse-engineering report (PDF + Markdown) in ~2 hours. $29 for one app, $19/app for batches.

Free samples: CamScanner teardown

Questions about Duolingo's stack? Comment below.

Introducing NitroIDE — Building a Faster Browser-Based IDE for Developers

Mon, 25 May 2026 17:32:29 +0000

Introducing NitroIDE — Engineering a Faster Browser IDE for Modern Developers

Hey everyone

Over the past few months, I’ve been working on a project called NitroIDE — a modern browser-based IDE focused on performance, low latency, and creating a smoother developer experience directly inside the browser.

The idea behind NitroIDE came from a simple frustration:

Most online code editors still don’t fully feel “native.”

Even though browser technology has improved massively over the years, many web-based development environments still suffer from small delays, cluttered interfaces, unnecessary complexity, and workflows that interrupt developer focus.

As developers, we spend hours every day inside editors.

Even tiny interruptions in responsiveness, animation smoothness, typing latency, navigation speed, or UI clarity can slowly reduce productivity and break flow state.

That’s the problem I wanted to explore.

Why Build Another Browser IDE?

Traditional online editors are often designed around remote execution and cloud infrastructure first.

While cloud-based development is incredibly powerful, the frontend experience itself sometimes becomes secondary.

I wanted to experiment with a different philosophy:

What if a browser IDE focused heavily on responsiveness, fluid interaction, and developer flow?

NitroIDE is my attempt at building a development environment that feels:

Fast
Lightweight
Modern
Responsive
Distraction-free
Smooth to interact with

The goal isn’t just to “run code in the browser.”

The goal is to make browser development feel enjoyable.

Core Areas I’m Focusing On

⚡ Frontend Performance Optimization

Performance is one of the biggest priorities in NitroIDE.

I’ve been experimenting with:

Faster rendering workflows
Optimized UI updates
Efficient state management
Lightweight interaction systems
Reduced visual clutter
Smooth editor responsiveness

Even small optimizations can dramatically improve how an application feels during daily use.

Developer Flow & UX

One thing I’ve realized while building products is that developer experience is deeply psychological.

Good tools help you stay focused.

Bad tools constantly interrupt your thinking.

NitroIDE is heavily focused on:

Cleaner interface design
Better visual hierarchy
Reduced distractions
Faster interactions
Simpler workflows
Minimal friction between idea and execution

I want the editor to feel almost invisible while coding.

Browser-Based Development Is Evolving

Modern browsers are becoming incredibly capable platforms.

With advancements in:

WebAssembly
Real-time rendering
Modern JavaScript engines
Edge infrastructure
Browser APIs
Real-time collaboration systems

…it feels like browser-based development tools are entering a completely new era.

NitroIDE is partly an exploration of what modern web technologies can achieve when performance and UX become first-class priorities.

Technologies & Areas I’m Exploring

Some of the areas involved while building NitroIDE include:

Full-stack web development
Frontend architecture
Real-time web systems
React & Next.js workflows
TypeScript-based architecture
WebSockets & live systems
Browser performance engineering
UI/UX systems
Developer tooling
Responsive design systems

The project continues evolving as I experiment, learn, and improve the architecture over time.

Challenges of Building Developer Tools

Building developer tools is honestly one of the most interesting technical challenges I’ve worked on.

Developers notice everything:

Latency
Interaction quality
UI consistency
Keyboard responsiveness
Layout behavior
Animation smoothness
Workflow friction

Small details matter much more in developer products than many people realize.

That’s also what makes building them exciting.

Long-Term Vision

My long-term vision for NitroIDE is to continue improving the browser development experience while experimenting with:

Faster workflows
Better performance
Real-time collaboration
AI-assisted development workflows
Modern editor experiences
More fluid developer interaction systems

I’m still continuously building, learning, testing ideas, and refining the platform.

Final Thoughts

This is still an evolving project, but I wanted to finally share it publicly and connect with other developers who are interested in modern web tooling, browser IDEs, frontend performance, and developer experience engineering.

I’d genuinely appreciate feedback, ideas, suggestions, or even criticism from fellow developers.

Website: https://nitroide.com

Thanks for reading

Building a Production-Ready .NET 9 & React SaaS Core (With Global Tenant Isolation)

Fri, 15 May 2026 18:16:57 +0000

Hey everyone!

Let’s be honest: the absolute worst part of starting a brand new SaaS idea is the first 40 hours of setup. Before you can even build the actual feature you're excited about, your momentum gets completely killed because you're stuck doing the boring stuff.

You have to configure JWT refresh tokens, make sure your database won't leak data between users, build a team invitation flow, and wrestle with Stripe webhook signatures.

I finally got tired of repeating this cycle every single time I wanted to launch something. So, over the last few weeks, I locked myself in a room and built a production-ready foundation using a Clean Architecture .NET 9 Web API and a super clean, dark-mode React + Tailwind CSS frontend.

I wanted to share a quick look at how it's put together under the hood!

How it handles the tricky parts

1. Simple, Secure Auth (No bloated packages)
Instead of fighting with massive, monolithic identity frameworks that are impossible to customize, I went with a lightweight JWT setup. It uses short-lived access tokens alongside database-backed refresh tokens. It keeps user sessions perfectly alive without sacrificing an ounce of security.

2. Bulletproof Tenant Isolation
Data leaking between companies is a total nightmare. To fix this, the database layer hooks into Entity Framework Core's global query filters.

Basically, the backend automatically sniffs out the TenantId from the user's secure token and injects it into every database query. You don't have to remember to type .Where(x => x.TenantId == current) on every single controller—it just works natively.

3. Plug-and-Play Stripe Webhooks
Handling asynchronous billing states can get messy fast. I set up a dedicated endpoint that listens for Stripe events (like successful checkouts or canceled subscriptions), verifies the webhook signature using your .env keys to keep things secure, and instantly flips the user's dashboard access state in real-time.

Want to skip the plumbing work this weekend?

I've packaged this entire engine into a minimal starter kit called SaaSGenesis. It includes a beautiful, high-end dashboard layout (I even cleared out the traditional, clunky client lists so the UI stays focused strictly on your core modules).

It’s officially live on Gumroad for $49, but I really want to get some honest feedback from fellow developers who are building cool stuff right now.

I’m giving away exactly 5 copies for 100% FREE.

If you are planning to build or launch something soon and want to skip a week of foundational setup:

Take a look at the project details here: https://yaman95.gumroad.com/l/saas-genesis

Building HOLO.SYS — A Futuristic 3D Holographic Visualization System with React, Three.js & GLSL

Fri, 08 May 2026 18:36:53 +0000

Introduction

Modern web development is rapidly evolving beyond traditional websites and static user interfaces. Today, developers are building immersive digital experiences directly inside the browser using technologies like WebGL, Three.js, GLSL shaders and advanced Web architectures.

As a Full Stack Web Developer, I always wanted to explore the creative side of Web engineering — where design, interaction, animation, performance and GPU rendering come together to create something visually powerful.

That vision led me to build HOLO.SYS — a futuristic cyberpunk-inspired 3D holographic visualization system developed using:

React.js
Three.js
GLSL Shader Programming
GSAP Animations
WebGL Rendering
Modern JavaScript Architecture

This project is not just another Web experiment.
It is a complete creative Web engineering project focused on immersive web experiences, real-time rendering, shader effects, and cinematic UI systems.

What is HOLO.SYS?

HOLO.SYS is a real-time interactive holographic visualization system inspired by:

Cyberpunk interfaces
Futuristic HUD systems
Sci-fi holographic displays
AI visualization panels
Advanced UI/UX concepts

The goal of this project was to simulate a futuristic holographic rendering system directly inside the browser using modern Web technologies.

The application features:

Real-time 3D rendering
Interactive camera controls
Dynamic holographic shader effects
Scanline visual systems
Animated glitch transitions
Fresnel rim glow lighting
Smooth geometry morph transitions
Live GUI customization controls
Performance optimized rendering

This project represents the combination of:

✅ Creative Development

✅ Modern Frontend Engineering

✅ WebGL Rendering

✅ Real-Time Graphics

✅ Interactive UI Systems

✅ Shader Programming

Live Project

⚛️ Technologies Used

One of the most exciting parts of this project was combining multiple modern frontend technologies together.

React.js

React was used to structure the application into reusable and scalable components.

It helped manage:

Component architecture
UI organization
Application structure
Rendering lifecycle
Future scalability

React makes it much easier to build modern interactive web applications while keeping the codebase clean and maintainable.

Three.js

Three.js was responsible for handling:

3D scene creation
Geometry rendering
Camera systems
Lighting setup
Mesh transformations
WebGL abstraction

Instead of manually writing low-level WebGL code, Three.js provides a powerful abstraction layer that allows developers to create advanced 3D experiences much faster.

The project includes multiple 3D geometries such as:

Torus Knot
Icosahedron
Torus Geometry

These objects transition dynamically with holographic effects.

GLSL Shader Programming

One of the most advanced parts of this project is the custom GLSL shader system.

The shaders were handwritten to create:

Holographic scanlines
Dynamic glitch displacement
Fresnel rim glow
Transparency falloff
Transition masking
Animated distortion systems

Vertex Shader Features

The vertex shader manipulates geometry positions in real-time.

It creates:

Glitch wave displacement
Randomized distortion
Progress-based transition effects
Animated geometry movement

Fragment Shader Features

The fragment shader controls:

Pixel colouring
Hologram transparency
Glow intensity
Fresnel lighting
Scanline rendering

This combination creates the cinematic holographic appearance visible in the final system.

GSAP Animations

GSAP was used to create smooth and performant animations.

It powers:

Geometry transitions
Shader progress animations
Smooth effect timing
UI interaction flow

GSAP provides better control and smoother animations compared to many traditional animation libraries.

WebGL Rendering

WebGL is the foundation behind the entire rendering pipeline.

It enables GPU acceleration directly inside the browser.

This allows the project to render:

Real-time graphics
Interactive 3D systems
Shader effects
Dynamic animations

without needing external software.

Major Features of HOLO.SYS

Real-Time Holographic Rendering

The project creates a futuristic holographic appearance using:

Transparency blending
Additive rendering
Glow effects
Scanline overlays
Animated distortion

The final output feels similar to sci-fi hologram systems seen in futuristic films and games.

Dynamic Glitch Effects

A custom glitch engine was developed using mathematical shader calculations.

The glitch system includes:

Time-based sine waves
Randomized displacement
Transition distortion
Multi-layered visual noise
Animated geometry corruption

These effects make the hologram feel alive and dynamic.

Fresnel Rim Glow

A Fresnel lighting system was implemented to create edge glow effects based on viewing angle.

This adds:

Depth perception
Futuristic glow
Cinematic visuals
Enhanced realism

This is one of the most visually impactful effects in the project.

Animated Object Transitions

The application cycles through multiple 3D geometries using shader-based transition masking.

Instead of instantly switching objects, the project creates:

Smooth vertical sweep transitions
Controlled visibility masking
Cinematic object replacement

This creates a much more polished and professional visual experience.

Interactive GUI Controls

A real-time GUI panel was implemented using lil-gui.

Users can dynamically change:

Hologram colors
Stage colors
Ambient lighting
Directional lighting

This makes the system interactive and customizable.

Performance Optimization

Performance was a major focus during development.

Optimization techniques include:

request Animation Frame loops
Controlled DPR scaling
Efficient shader calculations
Proper clean-up systems
Memory leak prevention
Optimized rendering pipeline

These improvements help maintain smooth rendering performance.

What I Learned From This Project

This project significantly improved my understanding of:

Advanced Web Development

I learned how modern Web engineering goes far beyond simple layouts.

Web development today includes:

Real-time rendering
GPU acceleration
Interactive systems
Creative coding
Visual programming

Shader Programming Concepts

Before this project, shader programming felt complex.

During development, I learned:

GLSL basics
Vertex shader manipulation
Fragment shader rendering
Coordinate systems
Lighting calculations
Procedural visual effects

This project became a huge learning experience.

Three.js Architecture

I gained practical experience with:

Scene management
Camera systems
Mesh rendering
Materials
Geometries
WebGL pipelines
Orbit Controls

This helped me better understand 3D development for the web.

Modern Full Stack Development Journey

As a Full Stack Developer, I believe modern web engineering should combine:

Functionality
Performance
Scalability
Creativity
User experience

HOLO.SYS represents that mindset.

It is not only a frontend showcase — it demonstrates creative engineering and technical exploration.

Why Creative Frontend Development Matters

The future of web development is moving toward:

Immersive experiences
3D interfaces
Interactive visual systems
AI-powered UIs
Real-time graphics
WebXR and AR/VR

Projects like HOLO.SYS help developers explore the next generation of web experiences.

Creative frontend engineering is becoming one of the most exciting areas in software development.

Future Improvements

This project is still evolving.

Future upgrades may include:

Bloom post-processing
Audio reactive effects
GLTF/GLB model loading
Mobile touch optimization
WebXR support
AI visualization systems
Advanced particle systems
Dynamic environment lighting
Procedural geometry systems
Cyberpunk dashboard integrations

The goal is to continue transforming HOLO.SYS into a more advanced interactive visualization framework.

About the Developer

Hi, I’m Muhammad Yasir — also known online as YasirAwan4831.

I’m a Full Stack Web Developer focused on:

Modern Web Development
Creative Frontend Engineering
React.js Applications
JavaScript Ecosystems
Three.js & WebGL
UI/UX Development
Interactive Web Experiences
Performance Optimization

I continuously work on improving my skills by building real-world projects and experimenting with modern technologies.

Final Thoughts

Building HOLO.SYS was an exciting journey into the world of:

Creative coding
Real-time graphics
WebGL rendering
Shader programming
Advanced frontend development

Projects like this remind me how powerful the modern web has become.

Today, browsers are capable of rendering cinematic experiences that once required dedicated graphics software.

More futuristic projects, advanced UI systems and immersive web experiences are coming soon.

Connect With Me

GitHub

https://github.com/YasirAwan4831

Project Repository

https://github.com/YasirAwan4831/holographic-shader-visualizer-three.Js

Live Demo

https://holographic-threejs.vercel.app/

#ReactJS #ThreeJS #WebGL #GLSL #ShaderProgramming #FrontendDevelopment #CreativeCoding #CyberpunkUI #WebDevelopment #JavaScript #GSAP #ModernWebDevelopment #InteractiveWebDesign #FullStackDeveloper #CreativeFrontend #RealtimeRendering #HolographicUI #OpenSource #UIUX #Programming #WebDesign #ThreejsProjects #ReactDeveloper #WebGLProjects #YasirAwan4831 #MuhammadYasir

I Built a Full-Stack E-Learning Platform with AI Quiz Generation — Here's Everything I Learned

Fri, 24 Apr 2026 21:16:50 +0000

I'm Karim, a full-stack developer and AI/ML researcher from Cairo. Over the past year, I built Qodrateman — a production e-learning platform now live at qodrateman.com, serving Arabic-speaking students across 12+ courses.
This isn't a "look what I made" post. It's the full breakdown — stack decisions, what broke, how I fixed it, and what I'd do differently. Let's get into it.

What Is Qodrateman?
An e-learning platform built for the Arabic-speaking market with:

Structured courses with instructor/learner role separation
JWT authentication + Role-Based Access Control (RBAC)
AI quiz generation — instructors get a full quiz in under 30 seconds
12+ live courses, 500+ authenticated users
Deployed on Vercel (frontend) + Render (backend) with zero downtime

The Stack — and the Reasoning Behind Every Choice
React + TypeScript + Tailwind CSS
E-learning UI state is genuinely complex — active course, current lesson, user progress, enrollment status. React handles this cleanly. TypeScript caught dozens of bugs before they ever hit production. Tailwind made responsive design fast without drowning in custom CSS.
Django REST Framework
DRF gives you serializers, viewsets, and a built-in admin panel out of the box. I had a fully functional backend faster than I've seen with any other framework. For REST APIs, it's still my first pick.
PostgreSQL
E-learning data is deeply relational — users, courses, lessons, enrollments, quiz attempts, all interconnected. PostgreSQL handles this naturally. SQLite is fine locally, but never in production.
JWT Auth with simplejwt
pythonREST_FRAMEWORK = {

'DEFAULT_AUTHENTICATION_CLASSES': (
    'rest_framework_simplejwt.authentication.JWTAuthentication',
),

}
Access token in memory (not localStorage — that's a security risk). Refresh token handles silent re-authentication. Frontend and backend stay fully decoupled.
Vercel + Render
Zero-config deploys on every push with Vercel. Render for the Django backend — free tier works at early stage, scales easily when needed. Total setup time: under 2 hours.

The Feature I'm Most Proud Of: AI Quiz Generation
Instructors told me quiz creation was their biggest time sink — around 20 minutes per quiz. Writing quality multiple-choice questions is genuinely hard.
I built AI-assisted quiz generation that brings that down to under 30 seconds.
Here's how it works:

Instructor enters topic + difficulty level
System sends a structured prompt to the AI API
API returns a complete quiz in JSON — questions, options, correct answers
Platform parses and saves it directly to the database
Instructor reviews and publishes in one click

The structured prompt was the key engineering decision:
pythondef generate_quiz_prompt(topic, num_questions, difficulty):

return f"""
Generate a quiz about: {topic}
Number of questions: {num_questions}
Difficulty: {difficulty}

Respond ONLY with valid JSON in this exact format:
{{
    "questions": [
        {{
            "question": "question text",
            "options": ["A", "B", "C", "D"],
            "correct_answer": "A",
            "explanation": "why this is correct"
        }}
    ]
}}
Do not include any text outside the JSON.
"""

Forcing structured output and validating before saving eliminated the inconsistency problem entirely. Early versions failed whenever the model returned extra text around the JSON — strict format constraints fixed this.

RBAC: Two User Types, Zero Overlap
Instructors and learners have completely separate capabilities. Here's the core of how that's modeled:
python# models.py
class UserProfile(models.Model):

ROLES = [
    ('instructor', 'Instructor'),
    ('learner', 'Learner'),
]
user = models.OneToOneField(User, on_delete=models.CASCADE)
role = models.CharField(max_length=20, choices=ROLES)

permissions.py

class IsInstructor(BasePermission):

def has_permission(self, request, view):
    return (
        request.user.is_authenticated and
        request.user.userprofile.role == 'instructor'
    )

This permission class protects every instructor-only endpoint — course creation, quiz generation, student progress. Learners can read published content and submit their own quiz attempts. Nothing more.

What Broke in Production (and How I Fixed It)
The N+1 Query Problem
The course listing API was slow. Every course card needed the instructor name, lesson count, and enrollment count — three queries per course. With 12+ courses, that's 36+ database hits per page load.
Fix:
pythoncourses = Course.objects.select_related('instructor').annotate(

lesson_count=Count('lessons'),
enrollment_count=Count('enrollments')

)
One query. Page load time dropped by 70%.
Inconsistent AI Responses
Early quiz generation would sometimes return extra text around the JSON, breaking json.loads().
Fix — strip everything outside the JSON object before parsing:
pythondef parse_ai_response(response_text):

try:
    start = response_text.index('{')
    end = response_text.rindex('}') + 1
    return json.loads(response_text[start:end])
except (ValueError, json.JSONDecodeError):
    raise ValidationError("AI response could not be parsed")

Render Cold Starts
Render's free tier spins down inactive services. First request after inactivity: 30+ seconds. Terrible UX.
Fix: a lightweight ping endpoint that a Vercel cron job hits every 14 minutes. Cost: zero. Cold starts for active users: eliminated.

What I'd Do Differently
Add React Query from day one. Managing server state with raw useEffect and useState gets messy fast. React Query handles caching, refetching, and loading states far more cleanly. I retrofitted it partway through — not fun.
Map the permission model before writing code. I refactored RBAC twice because I hadn't thought through edge cases upfront. Can instructors see other instructors' content? Can learners preview unenrolled courses? Draw this out before touching code.
Use Docker locally from the start. "Works on my machine" is a real problem. Docker Compose makes the jump from local to production significantly smoother.

By the Numbers
MetricResultCourses live12+Authenticated users500+Quiz generation time~20 min → under 30 secPost-launch rollbacks0Downtime since launch0

What's Next
I'm also building Letra — a custom-trained bilingual OCR mobile app for iOS and Android using TensorFlow, Keras, PaddleOCR, and OpenCV. Currently at 98% English accuracy on 800+ labeled samples, deployed to TestFlight and Google Play Beta. Arabic OCR is in active iteration targeting 85%+.

The hardest part of building a real product isn't writing the code. It's the decisions you make before you write any — schema design, permission models, deployment architecture. Get those right and everything else follows.
If you're building on Django + React or have questions about the AI quiz generation approach, drop a comment. Happy to dig into any part of this.

Full-stack dev & AI/ML researcher based in Cairo
karimkhamis.com · qodrateman.com · github.com/karim-99-99

From Chaos to Control: How GJSDocs Is Changing the Way Work with Document

Sun, 19 Apr 2026 22:30:38 +0000

In today’s fast-paced world of development and business, time is the most valuable resource. While some teams are still manually copying data into invoices, contracts, and reports, others are using automation tools. Today, we’re taking a look at GJSDocs — a platform that promises to eliminate "copy-paste" once and for all.

What is GJSDocs?

GJSDocs is a next-generation SaaS platform for document automation. The core concept is simple: you create a professional template once, connect your data (via API or integrations), and the service generates ready-to-use documents in seconds.

Key Features

Visual Template Editor: Forget about complex markup. The service offers a powerful builder where you can flexibly customize document structure, fonts, and styles to ensure a professional result.

Data Integration: The standout feature is the connection to your business. You can feed data from CRMs, databases, or other applications directly into variables within your document.

Next-Gen Automation: Positioned as a solution for "modern teams," it implies seamless collaboration, cloud storage, and high-speed generation.

API & Ecosystem: The "Integrations" section suggests that GJSDocs easily fits into any existing corporate workflow.

Who is it for?

Developers: Quickly implement PDF report or invoice generation into an app without spending weeks writing custom generation libraries.

HR & Legal: Streamline the creation of job offers, employment contracts, or NDAs.

Sales Departments: Automatically generate commercial proposals based on client data.

Why is it worth trying?

The main problem with manual document entry is human error. A typo in a contract amount or bank details can be costly. GJSDocs minimizes these risks because the data is pulled automatically from the primary source.

The platform’s interface is modern and clean, which is essential for tools used on a daily basis. The "Pricing" and "Documentation" sections indicate a transparent business model and readiness to scale for any business size.

Verdict

GJSDocs is a powerful tool for anyone looking to bring order to their documentation. It’s not just a "text editor" but a full-scale bridge between your data and the final PDF/Docx file.

If your team is still spending more than 10 minutes creating a standard document, it’s time to check out the GJSDocs Dashboard.

Website: https://gjsdocs.com/

Building Real Projects, One Step at a Time

Thu, 09 Apr 2026 18:34:35 +0000

Building Real Projects, One Step at a Time

As part of my internship at ARCH Technologies, I’ve successfully completed Task 3 — a Web-Based Music Player.

This project wasn’t just about building a UI, but about understanding how real applications work — handling user interactions, managing state and integrating external APIs.

I focused on creating a clean and modern experience where users can:
Search music dynamically
Play, pause, and control audio
Explore songs through categories
Navigate playlists smoothly

️ Tech Stack:
React (Vite) • JavaScript • Tailwind CSS • Music API

What made this project valuable for me was learning how to connect frontend logic with real-time data and create a smooth user experience.

Live Demo: https://yasirawaninfomusic.vercel.app/
GitHub Repo: https://github.com/YasirAwan4831/arch-Technologies-internship-task3-music-player

This is another step forward in my journey as a Full Stack Developer — more projects coming soon!

#React #JavaScript #AppDevelopment #WebDevelopment #Internship #Projects #MusicPlayer #WebDeveloper #FullStackDeveloper #MuhammadYasir #YasirTech #YasirAwan4831

Start Building Tables Faster with These Free Shadcn Table Components & Blocks

Mon, 06 Apr 2026 12:32:15 +0000

Tables are one of those components you don’t think about much… until you need one.

User lists, invoices, dashboards, analytics almost every app needs a way to display structured data. And building tables from scratch every time? That quickly becomes repetitive.

If you’re working with React or Next.js, using ready-made shadcn components can help you move faster without compromising flexibility.

Why Developers Are Switching to Shadcn Tables

If you've recently built something with React or Next.js, chances are you've come across shadcn.

The biggest reason? Control.

Unlike traditional table libraries like MUI Data Grid, Mantine, or TanStack Table, shadcn doesn’t lock you into a predefined system.

You can:

Style it the way you want
Extend features easily
Keep everything aligned with your design system

With shadcn tables, you're not fighting the library you're building on top of it.

Built tables using shadcn ?
Feel free to share it
I’d love to check it out and feature it here.

Official Shadcn Table with Actions

This is the official table component from the shadcn team.

It’s a solid starting point when you need actions like dropdown menus inside table rows.

Features

Responsive layout
Dropdown actions built-in
Available in Base UI and Radix UI versions

Built with: React, Tailwind, Base UI

⬇️ Get Code

Project Management Table (Dashboard Style)

A more advanced table layout designed for dashboards.

You get useful elements like avatars, progress indicators, and search helpful when managing team or project data.

Features

Dashboard-friendly layout
Profile image support

Built with: React, Next.js, Tailwind, Base UI, Radix UI

Live Preview • ⬇️ Get Code

Shadcn Table by Tailwindadmin

A clean and flexible table component built using Tailwind and shadcn.

It’s designed to work across multiple frameworks, so you can use it not just in React or Next.js, but also in Vue, Angular, or even plain HTML projects without much effort.

Features

Supports both light and dark mode
Comes with a complete admin template

Built with: Shadcn, Tailwind, React, Next.js, Vue, Angular, HTML

Live Preview • ⬇️ Download

Special Recognition: Shadcn Table Builder

An AI-powered table builder designed for Shadcn, React and Next.js projects.

It helps you quickly generate tables using JSON, API data, or even CSV uploads no need to build everything manually.

Perfect when you want to move fast and create dynamic tables without spending hours on setup.

Table with Checkbox Filter

An example built with Next.js for handling dynamic data.

Supports server-side pagination, sorting, and filtering with checkboxes.

Features

Pagination support
Dynamic data handling

Built with: TanStack, Next.js, Shadcn

Data Table with Sorting & Filters

If you're working with larger datasets, this one is useful.

It handles server-side filtering, sorting, and pagination while keeping the UI clean.

Features

Light and dark mode
Filtering and sorting

Built with: Next.js, Tailwind, Drizzle, Zod, Planetscale

Basic Data Table

A simple and minimal table for everyday use.

Great when you just need to display data without adding too many features.

Features

Clean UI
Badge support

Built with: TanStack, Shadcn, Tailwind, React, Zod

Shadcn Table Maker

This one is more like a helper tool.

It lets you create dynamic tables quickly without writing everything manually.

Features

Build custom tables
Works across multiple use cases

Built with: Next.js, Tailwind, Drizzle, Zod, Planetscale

Table for Music / Media Data

A unique example built using Rails with shadcn styling.

Shows that shadcn is not limited to just React — you can adapt it across stacks.

Features

Built for media or audio data

Built with: Ruby on Rails, Shadcn

Invoice Table

A clean table layout designed for invoice data.

Simple, readable, and easy to adapt for other structured data.

Features

Fully responsive
Clean layout

Built with: React, Tailwind, Base UI

Final Thoughts

Tables are everywhere in modern apps.

Instead of rebuilding the same UI again and again, using shadcn table components helps you save time and keep your UI consistent.

Pick a block, customize it based on your needs, and ship faster.

Need more Shadcn Table Components?

Explore more shadcn ui blocks to speed up your development workflow.

Shadcn Sidebar Patterns I’d Actually Use in a Real Project

Thu, 26 Mar 2026 11:44:52 +0000

In most SaaS dashboards, the sidebar is not just a menu.

It controls navigation, layout structure, permissions, and even performance. If you build with Next.js and React, your sidebar design will directly affect how scalable and maintainable your app becomes.

This article explains the most effective Shadcn sidebar patterns and how to think about them from a system design perspective.

A Shadcn sidebar is a navigation system built using shadcn/ui components and Tailwind CSS.

In real projects, it usually does the following:

Lives inside a shared dashboard layout
Persists across route changes
Highlights active routes
Supports role based access
Handles responsive behavior

In a Next.js App Router setup, the sidebar is placed inside layout.tsx under a dashboard route group. This prevents it from unmounting during navigation.

Typical structure:

app/  
  (dashboard)/  
    layout.tsx  
    page.tsx

Navigation items are stored in a config file and mapped into UI components. This keeps logic clean and avoids repeating code.

In small projects, developers hardcode links in JSX.

In large SaaS systems, that approach fails quickly.

A well designed sidebar improves:

Maintainability
Scalability
Developer productivity
Routing consistency
Permission handling
Performance

If your navigation grows from 10 items to 50 items, poor structure will create technical debt.

Architecture Decisions You Should Make First

Before choosing a sidebar style, answer these questions.

If your app has nested sections, use a config driven structure with children arrays and recursive rendering.

Example:

export const navItems = [  
  {  
    title: "Dashboard",  
    href: "/dashboard"  
  },  
  {  
    title: "Users",  
    children: [  
      { title: "All Users", href: "/users" },  
      { title: "Roles", href: "/users/roles" }  
    ]  
  }  
]

This keeps your components reusable and avoids large JSX blocks.

If you support collapse and expand behavior, store the state in:

React Context
Zustand
A global store

Do not store it inside a single component if you want layout persistence.

3. How will active routes be handled

In Next.js, use usePathname() to match the current path with navigation items.

Keep matching logic outside UI components. This makes the sidebar easier to test and reuse.

If your app has different roles, filter the navigation config before rendering.

Do not mix permission logic inside presentational components.

5. Is the app mobile friendly

Use the same navigation config for both desktop and mobile.

Render it as:

Fixed sidebar on desktop
Drawer or sheet on mobile

Never duplicate navigation logic for different screen sizes.

Here are the most practical patterns used in production dashboards.