Coder Legion - Recent posts tagged fastapi

Building an ATS Resume Scorer API with FastAPI, Celery, and Docker

Fri, 30 Oct 2026 07:57:26 +0000

Most resumes are filtered by ATS software before a human ever reads them. This project is a backend API that checks how well a resume matches a job description and suggests how to improve it.

What it does

PDF resume parsing: extracts text from uploaded resumes using pdfplumber
ATS keyword matching: compares the resume against a job description and calculates a match score
Smart suggestions: generates actionable tips to improve the resume for a specific role
JWT authentication: secured endpoints with role-based access for Job Seekers and Recruiters
Batch scoring: recruiters can score many resumes at once, handled in the background by Celery + Redis

Tech stack

Layer	Technology
Backend	Python, FastAPI
Auth	JWT (python-jose, passlib)
Database	MySQL 8.0, SQLAlchemy ORM, Alembic
Task queue	Celery + Redis
PDF parsing	pdfplumber
DevOps	Docker, Docker Compose, AWS EC2
CI/CD	GitHub Actions
Testing	Pytest

Design highlights

Background processing: batch scoring runs through a Celery queue, so the API stays responsive while many resumes are processed.
Role-based access: Job Seekers and Recruiters get separate permissions on the same API.
Reproducible setup: the whole stack (API, MySQL, Redis) starts with a single Docker Compose command.
Automated deployment: a GitHub Actions pipeline deploys automatically to AWS EC2.
Database migrations: schema changes are managed with Alembic.

Source code

https://github.com/priyadharshiny13/ats-resume-scorer

Feedback is welcome. If you were using a tool like this, what would matter more: a more accurate match score or more detailed improvement suggestions?

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.

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 Your First Production-Ready API with Python: A Complete Guide for Full Stack Developers

Sun, 11 Oct 2026 17:37:55 +0000

Application Programming Interfaces (APIs) are the backbone of modern software development. They allow different applications, services, and systems to communicate with each other. Whether you are building a web application, a mobile app, an e-commerce platform, or an AI-powered SaaS product, APIs play a critical role in delivering reliable and scalable functionality.

Python has become one of the most popular programming languages for API development because of its clean syntax, extensive ecosystem, and powerful frameworks. Developers can use Python to build everything from simple REST APIs to complex microservices that support thousands of users.

However, creating an API that works on your local computer is only the first step. A production-ready API must be secure, maintainable, well-documented, properly tested, observable, and capable of handling real-world traffic.

In this article, we will explore how to build your first production-ready API with Python. We will use FastAPI as our primary framework and examine essential concepts such as project structure, request validation, database integration, authentication, error handling, automated testing, logging, performance, and deployment.

The goal is not just to build an endpoint that returns data. It is to understand how professional developers design APIs that can be maintained and improved over time.

1. Understanding What Makes an API Production-Ready

Before writing code, it is important to understand the difference between a basic API and a production-ready API.

A basic API might accept a request, perform an operation, and return a response. That is sufficient for learning, but production environments introduce additional challenges.

For example, users may send invalid input, databases may become temporarily unavailable, attackers may attempt unauthorized access, and traffic may increase unexpectedly. Without proper safeguards, these situations can cause failures or expose sensitive information.

A production-ready API should include several essential characteristics.

Reliability: The API should handle expected failures gracefully and return consistent responses.

Security: Sensitive resources must be protected through authentication, authorization, input validation, and secure configuration.

Maintainability: The codebase should have a clear structure that makes it easy to understand, test, and extend.

Performance: Database queries, network operations, and request processing should be efficient.

Observability: Logs, metrics, and error reports should help developers understand what happens inside the application.

Documentation: Developers should be able to understand endpoints, request formats, response schemas, and authentication requirements.

Testing: Automated tests should verify that important functionality continues working after changes.

These qualities should influence the design from the beginning rather than being added as an afterthought.

2. Choosing Python and FastAPI

Python offers several frameworks for API development, including Flask, Django REST Framework, and FastAPI.

Flask is lightweight and flexible, making it suitable for small applications and projects that need a minimal framework. Django REST Framework is particularly useful when building APIs around Django applications that require an integrated ORM, administrative interface, and established authentication features.

FastAPI is an excellent choice for modern API projects because it supports asynchronous programming, automatic request validation, Python type hints, and automatically generated OpenAPI documentation.

It also works well with Pydantic, which provides structured data validation and serialization.

Consider a simple example:

from fastapi import FastAPI

app = FastAPI()

@app.get("/")
def home():
    return {"message": "Welcome to my API"}

When the application receives a GET request at the root endpoint, it returns a JSON response.

Although this example is small, it demonstrates the basic structure of a FastAPI application. The framework handles routing and converts the returned Python dictionary into a JSON response.

For a production project, we will expand this foundation with validation, persistence, testing, and security.

3. Setting Up the Development Environment

A clean development environment helps prevent dependency conflicts and makes a project easier to reproduce.

First, install Python and create a directory for the project.

mkdir production-api
cd production-api

Create a virtual environment:

python -m venv .venv

Activate it on Windows:

.venv\Scripts\activate

On macOS or Linux:

source .venv/bin/activate

Next, install the primary dependencies:

pip install fastapi "uvicorn[standard]" sqlalchemy \
  psycopg[binary] pydantic-settings \
  pyjwt "pwdlib[argon2]" pytest httpx

These packages serve different purposes:

FastAPI provides API routing and request handling.
Uvicorn runs the application as an ASGI server.
SQLAlchemy provides database access and ORM functionality.
Psycopg connects Python applications to PostgreSQL.
Pydantic Settings manages configuration.
PyJWT supports JSON Web Token operations.
pwdlib with Argon2 supports secure password hashing.
Pytest and HTTPX support automated API testing.

For a real project, record the exact tested dependency versions in a lockfile or another reproducible dependency-management workflow. Keep development tools separate from production dependencies where appropriate.

4. Designing a Maintainable Project Structure

As an application grows, placing every endpoint, database operation, and validation rule inside one Python file becomes difficult to maintain.

A modular structure separates responsibilities and improves readability.

One possible project layout is:

production-api/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── config.py
│   ├── database.py
│   ├── models.py
│   ├── schemas.py
│   ├── security.py
│   └── routers/
│       ├── __init__.py
│       └── tasks.py
├── tests/
│   └── test_tasks.py
├── .env
├── .gitignore
└── requirements.txt

Each module has a specific responsibility.

The main application initializes FastAPI and registers routers. Configuration manages environment-specific settings. Database code creates database connections and sessions. Models describe database tables, while schemas define the structure of incoming and outgoing data.

Routers group related endpoints, and tests verify application behavior.

This organization makes it easier to add features without turning the codebase into a tightly connected collection of functions.

The ideal structure depends on the size of the application. A small API does not need dozens of folders, but even a small project benefits from clear separation between business logic, persistence, and HTTP handling.

5. Building the Main Application

Create app/main.py:

from fastapi import FastAPI
from app.routers import tasks

app = FastAPI(
    title="Production Tasks API",
    version="1.0.0",
    description="A practical task management API"
)

app.include_router(tasks.router, prefix="/api/v1")

@app.get("/health/live", tags=["Health"])
def liveness():
    return {"status": "alive"}

This creates the application and registers a router under the /api/v1 prefix.

Versioning endpoints helps developers evolve an API without unexpectedly breaking existing clients. A future version can introduce different response formats or behavior while the previous version remains available during migration.

The liveness endpoint provides a simple indication that the application process can respond. It does not prove that PostgreSQL or every external dependency is available. A separate readiness check can verify whether the service is ready to receive traffic.

FastAPI also generates interactive API documentation by default at /docs and an OpenAPI schema at /openapi.json.

These features are particularly helpful when frontend developers, mobile developers, and third-party integrators need to understand how the API works.

6. Managing Configuration Safely

Production applications should not depend on hardcoded database passwords, secret keys, or environment-specific URLs.

Instead, use environment variables or a dedicated secrets manager.

Create app/config.py:

from pydantic_settings import BaseSettings, SettingsConfigDict

class Settings(BaseSettings):
    database_url: str
    jwt_secret: str

    model_config = SettingsConfigDict(
        env_file=".env",
        extra="ignore"
    )

settings = Settings()

A local .env file might contain:

DATABASE_URL=postgresql+psycopg://user:password@localhost/tasks
JWT_SECRET=replace-with-a-long-random-secret

The example values are placeholders. Replace them with actual credentials for your development environment.

Add .env to .gitignore so credentials are not accidentally committed to Git.

In production, inject secrets through the deployment platform or a secrets manager instead of distributing a local .env file. Use a strong, randomly generated signing key, rotate credentials when necessary, and never expose them in API responses or logs.

Configuration validation also helps the application fail early when required settings are missing.

7. Connecting to PostgreSQL

Many APIs need persistent storage. PostgreSQL is a strong choice because it supports relational data, transactions, indexes, and advanced querying capabilities.

Create app/database.py:

from sqlalchemy import create_engine
from sqlalchemy.orm import DeclarativeBase, sessionmaker

from app.config import settings

engine = create_engine(
    settings.database_url,
    pool_pre_ping=True
)

SessionLocal = sessionmaker(
    bind=engine,
    autoflush=False,
    expire_on_commit=False
)

class Base(DeclarativeBase):
    pass

The engine manages connections to the database, while SessionLocal creates database sessions.

The pool_pre_ping=True option checks pooled connections before using them, helping detect connections that have become invalid.

Next, define a database model in app/models.py:

from sqlalchemy import Boolean, String, Text
from sqlalchemy.orm import Mapped, mapped_column

from app.database import Base

class Task(Base):
    __tablename__ = "tasks"

    id: Mapped[int] = mapped_column(
        primary_key=True
    )
    title: Mapped[str] = mapped_column(
        String(200),
        index=True
    )
    description: Mapped[str | None] = mapped_column(
        Text,
        nullable=True
    )
    completed: Mapped[bool] = mapped_column(
        Boolean,
        default=False
    )

The model defines a task with an identifier, title, optional description, and completion status.

In a production system, database schema changes should be managed with migrations, such as Alembic, instead of relying on automatic table creation during application startup.

Migrations provide a controlled way to introduce columns, indexes, constraints, and other structural changes without losing existing data.

8. Validating Incoming and Outgoing Data

Input validation is one of the most important responsibilities of an API.

Without validation, clients may submit missing fields, excessively long strings, unexpected values, or data in the wrong format.

Create app/schemas.py:

from pydantic import BaseModel, ConfigDict, Field

class TaskCreate(BaseModel):
    title: str = Field(
        min_length=1,
        max_length=200
    )
    description: str | None = Field(
        default=None,
        max_length=2000
    )

class TaskUpdate(BaseModel):
    title: str | None = Field(
        default=None,
        min_length=1,
        max_length=200
    )
    description: str | None = Field(
        default=None,
        max_length=2000
    )
    completed: bool | None = None

class TaskRead(BaseModel):
    id: int
    title: str
    description: str | None
    completed: bool

    model_config = ConfigDict(
        from_attributes=True
    )

These schemas define the expected shape of task data.

TaskCreate validates new tasks. TaskUpdate supports partial updates, while TaskRead defines the public representation returned by the API.

Using separate schemas prevents clients from directly controlling internal database fields.

For example, a client should not be able to set an administrative flag or assign a different user's identifier simply by including extra JSON properties in a request.

Validation does not replace authorization, but it reduces the amount of unexpected data that reaches the application's business logic.

9. Implementing CRUD Endpoints

CRUD stands for Create, Read, Update, and Delete. These operations form the foundation of many business APIs.

First, create a database-session dependency in app/database.py:

from collections.abc import Generator

def get_db() -> Generator:
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()

The dependency creates a session for each request and closes it when the request finishes.

Now create app/routers/tasks.py:

from fastapi import APIRouter, Depends, HTTPException, Response
from sqlalchemy import select
from sqlalchemy.orm import Session

from app.database import get_db
from app.models import Task
from app.schemas import TaskCreate, TaskRead, TaskUpdate

router = APIRouter(
    prefix="/tasks",
    tags=["Tasks"]
)

@router.post("/", response_model=TaskRead, status_code=201)
def create_task(
    payload: TaskCreate,
    db: Session = Depends(get_db)
):
    task = Task(**payload.model_dump())
    db.add(task)
    db.commit()
    db.refresh(task)
    return task

@router.get("/", response_model=list[TaskRead])
def list_tasks(
    db: Session = Depends(get_db)
):
    return db.scalars(
        select(Task).order_by(Task.id)
    ).all()

@router.get("/{task_id}", response_model=TaskRead)
def get_task(
    task_id: int,
    db: Session = Depends(get_db)
):
    task = db.get(Task, task_id)

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

    return task

@router.patch("/{task_id}", response_model=TaskRead)
def update_task(
    task_id: int,
    payload: TaskUpdate,
    db: Session = Depends(get_db)
):
    task = db.get(Task, task_id)

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

    changes = payload.model_dump(exclude_unset=True)

    for field, value in changes.items():
        setattr(task, field, value)

    db.commit()
    db.refresh(task)
    return task

@router.delete("/{task_id}", status_code=204)
def delete_task(
    task_id: int,
    db: Session = Depends(get_db)
):
    task = db.get(Task, task_id)

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

    db.delete(task)
    db.commit()
    return Response(status_code=204)

This router provides a basic task management API.

The POST endpoint creates a task. GET endpoints retrieve all tasks or a single task. PATCH updates selected fields, and DELETE removes a task.

Returning appropriate HTTP status codes improves consistency. For example, 201 Created indicates successful resource creation, 404 Not Found indicates a missing resource, and 204 No Content indicates successful deletion without a response body.

This implementation is a useful learning foundation, but it is not yet suitable for unrestricted public deployment. The list endpoint needs pagination, database errors need appropriate handling, and every task operation must enforce authorization once users are introduced.

10. Adding Authentication and Authorization

Authentication answers the question, "Who is making this request?" Authorization answers, "What is this user allowed to access?"

These are different responsibilities.

An API that allows users to manage private tasks must ensure that one user cannot read, update, or delete another user's data.

A common approach is to authenticate users with securely hashed passwords and issue access tokens after successful login.

Password hashing should use a dedicated password-hashing algorithm such as Argon2. Passwords must never be stored in plain text or encrypted with a reversible method when hashing is appropriate.

JSON Web Tokens (JWTs) are often used to represent authenticated sessions. A signed access token may contain a subject identifying the user and an expiration timestamp.

However, a signed token is not automatically encrypted. Its contents should not include passwords, private secrets, or unnecessary sensitive information.

A production authentication flow should generally include:

User registration with strict input validation.
Password hashing using an appropriate password-hashing algorithm.
Login verification and controlled token issuance.
Short-lived access tokens with validated expiration and signing algorithms.
Authorization checks on protected resources.
A secure token renewal or reauthentication strategy.
Rate limiting and monitoring for repeated failed login attempts.

When using OAuth2 or JWT bearer tokens with FastAPI, developers can use the framework's security utilities and validate tokens centrally.

Most importantly, authentication must be connected to data ownership. Adding a login endpoint alone does not protect task records.

For example, a task model might include an owner_id foreign key. A database query for a task should then verify that both the task identifier and the authenticated user's identifier match.

Conceptually:

task = db.scalar(
    select(Task).where(
        Task.id == task_id,
        Task.owner_id == current_user.id
    )
)

This query illustrates the ownership check; it assumes that the model contains owner_id and that current_user comes from a correctly implemented authentication dependency.

For a private resource, returning a not-found response for records the user cannot access can also reduce unintended disclosure of resource existence.

11. Handling Errors Consistently

Errors are inevitable in production systems. A client may send invalid data, a requested record may not exist, or a database operation may fail.

The API should return understandable errors without exposing internal implementation details.

FastAPI's HTTPException is useful for expected HTTP failures.

For example:

from fastapi import HTTPException

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

FastAPI automatically converts this exception into an appropriate HTTP response.

Validation errors are also handled by the framework. Developers should avoid catching every exception and returning a successful response because this hides failures and makes debugging difficult.

Unexpected exceptions should be logged internally and translated into safe client-facing error responses. The response should not contain database connection strings, stack traces, secret keys, or sensitive user information.

A consistent error format helps frontend applications display useful messages and handle failures predictably.

For example, a team may adopt a standard structure containing an error code, a human-readable message, and an optional request identifier.

The exact format matters less than applying it consistently across the application.

12. Improving Performance with Pagination and Indexing

An API that works well with ten records may struggle when a database contains millions of records.

Returning every row from a table is rarely a good default for a public endpoint. It can consume memory, increase response times, and place unnecessary pressure on the database.

Pagination allows clients to request a manageable subset of records.

For example, a list endpoint might accept a page size and a cursor or offset. The API should enforce a maximum page size to prevent clients from requesting excessively large responses.

Cursor-based pagination is often preferable for large or frequently changing datasets because it can provide more stable navigation when new records are added.

Database indexes also improve performance when queries repeatedly filter or sort by particular fields. However, indexes require additional storage and can slow down writes, so they should be selected based on actual query patterns.

Other performance improvements include:

Selecting only the columns the application needs.
Avoiding unnecessary database queries.
Using appropriate connection-pool settings.
Applying caching to suitable read-heavy endpoints.
Moving long-running jobs to background workers.
Profiling slow endpoints before attempting complex optimizations.

Asynchronous endpoints can improve concurrency for I/O-bound workloads, but they are not automatically faster in every situation. Blocking operations inside an asynchronous handler can undermine the expected benefits.

Use asynchronous database drivers and compatible libraries when an asynchronous architecture is appropriate, and measure the result rather than relying on assumptions.

13. Testing the API Before Deployment

Testing helps developers identify defects before users encounter them.

A production-ready API should have tests for normal behavior, invalid input, missing resources, permissions, and important failure scenarios.

Create tests/test_tasks.py:

from fastapi.testclient import TestClient

from app.main import app

client = TestClient(app)

def test_liveness_endpoint():
    response = client.get("/health/live")

    assert response.status_code == 200
    assert response.json() == {"status": "alive"}

Run the test with:

pytest

This test verifies that the application responds correctly to a liveness request.

For the task endpoints, additional tests should verify that valid requests create records, invalid requests return validation errors, nonexistent tasks return 404, and updates change only the intended fields.

Database tests should use an isolated test database or a controlled test fixture rather than modifying production data.

Authentication tests should also confirm that anonymous users cannot access protected resources and that one user cannot access another user's records.

Integration tests can verify interactions between FastAPI, PostgreSQL, and other services. End-to-end tests can validate complete workflows from the client's perspective.

A useful testing strategy combines fast unit tests with integration tests that cover the boundaries where failures are most likely.

14. Logging and Monitoring in Production

Once an API is deployed, developers need visibility into its behavior.

Logging provides a record of important events, while monitoring helps teams identify trends and emerging problems.

Useful production metrics include request volume, latency, error rates, database connection usage, and resource consumption.

Structured logging makes events easier to search and analyze. For example, a log entry may include the endpoint, HTTP status code, duration, and a request identifier.

However, logs should not contain passwords, access tokens, sensitive request bodies, or unnecessary personal information.

A request identifier can help developers trace an error across several services without exposing user credentials.

Monitoring alerts should focus on meaningful conditions, such as a sustained increase in server errors, a sharp rise in response times, or database connection exhaustion.

Health checks should be designed carefully. A liveness check should determine whether the process is functioning, while a readiness check can indicate whether the service can accept traffic based on critical dependencies.

Logging and monitoring are not simply operational extras. They help teams discover issues before those issues affect a large number of users.

15. Protecting the API Against Common Security Risks

Security needs to be considered throughout the development process.

Input validation: Validate request bodies, query parameters, path parameters, and file uploads. Set reasonable limits on field lengths and payload sizes.

Authentication: Require valid credentials for protected endpoints and validate token expiration, signatures, and expected claims.

Authorization: Check permissions for every protected operation, including access to individual records.

Rate limiting: Limit excessive requests, especially for login, password recovery, expensive searches, and other abuse-prone operations.

Transport security: Use HTTPS in production to protect information transmitted between clients and the API.

CORS configuration: Allow only the browser origins that need access. CORS is not a substitute for authentication or authorization.

Secret management: Keep credentials outside source control and restrict access to production secrets.

Dependency management: Regularly update dependencies, review security advisories, and remove unnecessary packages.

Database security: Use a dedicated database account with only the permissions required by the application.

Resource limits: Restrict request sizes, page sizes, execution times, and other resource-intensive operations.

Safe error responses: Avoid returning stack traces or internal system details to clients.

Security testing should include attempts to access resources without permission and attempts to bypass validation rules.

A secure API is not defined by the number of security libraries it uses. It is defined by whether its controls correctly protect data and enforce the application's rules.

16. Documenting the API for Other Developers

Good documentation reduces confusion and speeds up integration.

FastAPI generates interactive documentation based on route definitions, type hints, and Pydantic schemas.

Developers can visit /docs to inspect endpoints, review request and response formats, and try API calls.

For a production API, documentation should also explain authentication requirements, pagination behavior, error codes, rate limits, and any important business rules.

Endpoint descriptions should be clear enough that another developer can understand how to use the API without reading its internal implementation.

When an API changes, its documentation and tests should be updated together.

For teams maintaining multiple API versions, a documented deprecation policy helps clients migrate without unexpected interruptions.

Clear documentation is part of the API's developer experience, not merely a feature of the framework.

17. Preparing the API for Deployment

After implementation and testing, the API needs a reliable deployment process.

A typical deployment pipeline includes installing dependencies, running automated tests, checking configuration, applying database migrations, and deploying the application to a server or container platform.

For a basic local run, use:

uvicorn app.main:app --reload

The reload option is intended for development because it automatically restarts the application when files change.

For production, run the application using a suitable ASGI server configuration and a managed process or container platform. Configure worker processes according to the platform, available resources, and workload.

A Docker image can package the application and its dependencies into a reproducible deployment unit. PostgreSQL should generally run as a separate service rather than being embedded in the API container.

Production configuration should include the database connection string, signing keys, allowed origins, logging settings, and other environment-specific values.

Database migrations should run through a controlled release process. The application should not unexpectedly change the database schema every time a worker starts.

A mature deployment process also needs automated rollback or recovery procedures, database backups, and a strategy for handling incompatible schema changes.

Deploying the code is only one part of releasing a reliable service. The surrounding operational process matters just as much.

18. Using Docker for Consistent Environments

Docker helps teams reduce differences between development, testing, and production environments.

A simplified Dockerfile might look like this:

FROM python:3.12-slim

ENV PYTHONDONTWRITEBYTECODE=1
ENV PYTHONUNBUFFERED=1

WORKDIR /app

COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY app ./app

RUN useradd --create-home appuser
USER appuser

EXPOSE 8000

CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8000"]

This example uses a slim Python image, installs dependencies, copies the application code, and runs the server as a non-root user.

A complete production setup should pin and verify dependency versions, use a maintained base image, scan images for vulnerabilities, and configure appropriate resource limits.

The application also needs valid environment variables and access to its database when the container starts.

Do not include .env files, passwords, or private keys in the Docker image. Inject sensitive configuration securely at runtime.

For a real deployment, add a suitable readiness check and coordinate application startup with database availability. Container orchestration platforms can manage restarts and scaling, but they cannot compensate for incorrect application logic or unsafe database migrations.

19. Automating Quality Checks with CI/CD

Continuous Integration and Continuous Deployment (CI/CD) help teams deliver changes more reliably.

A CI pipeline can run automatically whenever a developer pushes code or opens a pull request.

Typical pipeline steps include:

Installing pinned dependencies.
Checking code formatting and style.
Running static analysis and type checks.
Running unit tests.
Running integration tests against a test database.
Scanning dependencies for known vulnerabilities.
Building the deployment image.
Publishing and deploying an approved release.

Automation catches problems earlier and reduces the risk of deploying code that has not been tested.

Secrets should be stored in the CI/CD platform's protected secret-management facilities, not committed to the repository.

Production deployments should also include approval controls where appropriate, health verification after release, and a rollback strategy if the new version fails.

Even a small personal project can benefit from a simple pipeline that runs tests and checks before each release.

20. Common Mistakes Developers Should Avoid

Many API problems result from shortcuts that appear harmless during early development.

One common mistake is putting all application logic in a single file. This makes it difficult to isolate responsibilities as the codebase grows.

Another is returning every database record without pagination. Large responses can degrade both server and client performance.

Developers also sometimes assume that hidden buttons or frontend checks provide security. They do not. Authorization must be enforced by the server.

Hardcoding secrets is another dangerous practice because credentials can leak through repositories, logs, and deployment artifacts.

Poor error handling creates additional problems. Returning raw exception messages may reveal sensitive implementation details, while silently ignoring exceptions makes failures difficult to diagnose.

Skipping automated tests increases the chance that a small code change will break an existing feature.

Finally, many developers optimize too early. Introducing complex caching, asynchronous patterns, or microservices before measuring actual bottlenecks can increase complexity without improving performance.

The better approach is to establish clear requirements, build a maintainable foundation, test critical behavior, and use production measurements to guide improvements.

21. A Practical Production-Readiness Checklist

Before releasing your Python API, review the following areas.

Application design

Clear project structure and separation of responsibilities.
Versioned endpoints and documented request/response schemas.
Consistent HTTP status codes and error handling.

Database

Controlled schema migrations.
Proper indexes and efficient queries.
Connection-pool configuration and backup procedures.

Security

Authentication and resource-level authorization.
Secure password hashing and token validation.
HTTPS, safe CORS settings, rate limiting, and secret management.

Testing

Unit and integration tests.
Validation and error-handling tests.
Permission and cross-user access tests.

Operations

Structured logs and useful metrics.
Liveness and readiness checks.
Reproducible deployments and recovery procedures.

Maintenance

Dependency updates and security reviews.
Automated CI checks.
Current documentation and a plan for API version changes.

Not every project requires a complex infrastructure from day one. The objective is to identify the risks that matter for the application's users and address them proportionately.

Conclusion

Building your first production-ready API with Python is an important milestone for any full stack developer. It teaches much more than defining routes and returning JSON responses. It requires thinking about data integrity, authentication, authorization, error handling, performance, testing, deployment, and long-term maintenance.

FastAPI provides a powerful foundation for this work through type-driven validation, automatic documentation, and support for modern Python application patterns. Combined with PostgreSQL, SQLAlchemy, automated testing, and a secure deployment workflow, it can support applications ranging from small business tools to sophisticated backend services.

The most important lesson is that production readiness is not a single feature or final development step. It is the result of many small engineering decisions made throughout the project.

Start with a clear architecture, implement one feature at a time, validate inputs, protect user data, and test the behavior that matters most. Add monitoring and automation before real users depend on the service.

Once you understand these fundamentals, you will be better prepared to build reliable APIs for web applications, mobile platforms, e-commerce systems, and AI-powered products.

A successful API is not simply one that works when everything goes right. It is one that behaves predictably, protects its users, and remains maintainable when real-world conditions become complicated.

Building a High-Throughput Article-to-Markdown API for LLM Ingestion with FastAPI and Playwright

Mon, 05 Oct 2026 08:36:31 +0000

Feeding raw HTML into LLM context windows is one of the most expensive and inefficient mistakes in modern AI engineering.

A standard modern news or blog page easily spans 1.5MB to 4MB of raw DOM payload. When passed straight into an LLM or vector database, 90% of those tokens are spent on tracking scripts, serialized JSON-LD blobs, cookie banners, navigation menus, and inline CSS styles. This not only causes severe context bloat and escalates inference bills, but it also degrades retrieval-augmented generation (RAG) semantic search precision by polluting your vector space with boilerplate noise.

Here is how to design and build an enterprise-grade, self-hosted extraction microservice using FastAPI, Trafilatura, Readability, and an asynchronous Playwright fallback for SPA rendering.

1. The Bottleneck: Commercial APIs vs. Fragile Scrapers

Most teams start with simple libraries like BeautifulSoup or newspaper3k. These quickly break down:

Layout Brittleness: Custom CSS selectors degrade when publishers redesign their DOM or randomize class names (e.g., CSS Modules/Tailwind compiles).
Client-Side Rendering (CSR): Single-page applications built on React, Next.js, or Vue return empty <div id="root"></div> shells to standard HTTP clients.
Commercial SaaS Overkill: Hosted extraction APIs charge upwards of $0.002 to $0.01 per page. If your pipeline indexes 200,000 URLs monthly, you are paying hundreds of dollars for what essentially amounts to an HTTP request and an AST traversal.

To balance latency, compute cost, and reliability, the optimal architecture uses a tiered extraction waterfall:

Tier 1 (Fast Path): High-speed async HTTP fetch + trafilatura. Latency: ~150-300ms.
Tier 2 (Heuristic Fallback): If Trafilatura fails or yields empty strings, fall back to Mozilla's readability-lxml algorithm.
Tier 3 (Headless Browser Fallback): If client-side hydration or dynamic script loading is detected, trigger an isolated headless Playwright worker to render the DOM before extraction.

2. System Architecture

[Incoming Request: URL]
          │
          ▼
┌───────────────────┐
│ Redis Cache Check │ ──(Hit)──► Return Markdown & Metadata
└───────────────────┘
          │ (Miss)
          ▼
┌───────────────────┐
│ HTTPX Async Fetch │
└───────────────────┘
          │
    [Static HTML]
          │
          ▼
┌───────────────────┐
│    Trafilatura    │ ──(Success: Length > Threshold)──► Parse Meta & Return
└───────────────────┘
          │ (Failed / Empty)
          ▼
┌───────────────────┐
│ Readability-lxml  │ ──(Success: Length > Threshold)──► Parse Meta & Return
└───────────────────┘
          │ (Failed / SPA Detected)
          ▼
┌───────────────────┐
│ Playwright Worker │ ──(Render DOM)──► Re-extract via Trafilatura
└───────────────────┘
          │
          ▼
[Store in Cache & Return Markdown]

This setup allows 85% of standard web content to pass through the lightweight Python tier without launching Chromium, keeping memory usage stable and infrastructure costs near zero.

3. Implementation: Code & Core Logic

Below is the complete implementation of the dual-engine pipeline using FastAPI, Pydantic v2, and async execution.

3.1 Pydantic Validation & Schemas

from pydantic import BaseModel, HttpUrl, Field
from typing import Optional, Dict, Any
from datetime import datetime

class ExtractionRequest(BaseModel):
    url: HttpUrl
    force_playwright: bool = Field(default=False, description="Bypass fast path and force browser rendering")
    max_chars: Optional[int] = Field(default=None, description="Truncate body content for token limits")

class PageMetadata(BaseModel):
    title: Optional[str] = None
    author: Optional[str] = None
    published_date: Optional[str] = None
    site_name: Optional[str] = None
    reading_time_minutes: int = 0
    opengraph: Dict[str, Any] = {}

class ExtractionResponse(BaseModel):
    url: str
    markdown: str
    metadata: PageMetadata
    engine_used: str
    execution_time_ms: float

3.2 The Dual-Engine Core Service

import time
import httpx
import trafilatura
from readability import Document
from bs4 import BeautifulSoup
from markdownify import markdownify as md
from playwright.async_api import async_playwright

USER_AGENT = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36"

async def fetch_html_fast(url: str) -> str:
    async with httpx.AsyncClient(timeout=10.0, follow_redirects=True) as client:
        response = await client.get(url, headers={"User-Agent": USER_AGENT})
        response.raise_for_status()
        return response.text

async def fetch_html_playwright(url: str) -> str:
    async with async_playwright() as p:
        browser = await p.chromium.launch(headless=True, args=["--no-sandbox", "--disable-dev-shm-usage"])
        context = await browser.new_context(user_agent=USER_AGENT)
        page = await context.new_page()
        await page.goto(url, wait_until="networkidle", timeout=20000)
        content = await page.content()
        await browser.close()
        return content

def extract_metadata(html: str) -> PageMetadata:
    soup = BeautifulSoup(html, "lxml")
    og_data = {}
    for tag in soup.find_all("meta"):
        prop = tag.get("property", tag.get("name", ""))
        if prop.startswith("og:") or prop.startswith("twitter:"):
            og_data[prop] = tag.get("content", "")

    title = og_data.get("og:title") or (soup.title.string if soup.title else None)
    author = og_data.get("article:author") or og_data.get("twitter:creator")
    pub_date = og_data.get("article:published_time")

    return PageMetadata(
        title=title,
        author=author,
        published_date=pub_date,
        site_name=og_data.get("og:site_name"),
        opengraph=og_data
    )

def extract_content(html: str, url: str) -> tuple[str, str]:
    # Primary Engine: Trafilatura
    extracted = trafilatura.extract(
        html,
        url=url,
        output_format="markdown",
        include_links=True,
        include_images=False,
        favor_recall=False
    )
    if extracted and len(extracted.strip()) > 200:
        return extracted, "trafilatura"

    # Fallback Engine: Readability + Markdownify
    doc = Document(html)
    summary_html = doc.summary()
    markdown_output = md(summary_html, heading_style="ATX").strip()
    
    if len(markdown_output) > 100:
        return markdown_output, "readability"

    return "", "none"

3.3 The FastAPI Microservice Route

from fastapi import FastAPI, HTTPException, status

app = FastAPI(title="Article-to-Markdown Extraction API", version="1.0.0")

@app.post("/api/v1/extract", response_model=ExtractionResponse)
async def extract_article(payload: ExtractionRequest):
    start_time = time.perf_counter()
    url_str = str(payload.url)
    engine_used = "trafilatura"
    
    try:
        if payload.force_playwright:
            html = await fetch_html_playwright(url_str)
            markdown, engine_used = extract_content(html, url_str)
            engine_used = f"playwright+{engine_used}"
        else:
            # Tier 1 & 2: Fast HTTP path
            try:
                html = await fetch_html_fast(url_str)
                markdown, engine_used = extract_content(html, url_str)
            except Exception:
                markdown = ""
            
            # Tier 3: SPA / Fallback if empty
            if not markdown or len(markdown.strip()) < 150:
                html = await fetch_html_playwright(url_str)
                markdown, engine_used = extract_content(html, url_str)
                engine_used = f"playwright_fallback+{engine_used}"

        if not markdown:
            raise HTTPException(
                status_code=status.HTTP_422_UNPROCESSABLE_ENTITY,
                detail="Failed to extract meaningful content from the target URL."
            )

        metadata = extract_metadata(html)
        words = len(markdown.split())
        metadata.reading_time_minutes = max(1, round(words / 200))

        if payload.max_chars and len(markdown) > payload.max_chars:
            markdown = markdown[:payload.max_chars] + "\n\n[Content Truncated]"

        exec_duration = (time.perf_counter() - start_time) * 1000

        return ExtractionResponse(
            url=url_str,
            markdown=markdown,
            metadata=metadata,
            engine_used=engine_used,
            execution_time_ms=round(exec_duration, 2)
        )

    except HTTPException:
        raise
    except Exception as e:
        raise HTTPException(status_code=status.HTTP_500_INTERNAL_SERVER_ERROR, detail=str(e))

4. Deployment, Caching & Concurrency Hardening

When exposing this service in production pipelines (e.g., connecting n8n webhooks or feeding continuous Celery queues), consider these three safeguards:

Browser Resource Constraints

Launching a new Chromium instance via async_playwright on every request will instantly lead to Linux OOM crashes. In a production build:

Maintain a single long-lived Browser instance.
Create and destroy lightweight BrowserContext sessions per request.
Enforce --disable-dev-shm-usage and --no-sandbox flags inside your Docker container.

Redis Caching Layer

Articles rarely mutate hourly. Adding an upstream Redis cache using a SHA-256 hash of the normalized canonical URL drastically drops response times to sub-10ms for repeated requests:

import hashlib

def generate_cache_key(url: str) -> str:
    normalized = url.split("?")[0].rstrip("/").lower()
    return f"extract:{hashlib.sha256(normalized.encode()).hexdigest()}"

Docker Container Configuration

FROM python:3.11-slim

ENV PYTHONUNBUFFERED=1 \
    PIP_NO_CACHE_DIR=1 \
    PLAYWRIGHT_BROWSERS_PATH=/ms-playwright

WORKDIR /app
RUN apt-get update && apt-get install -y --no-install-recommends \
    libxml2-dev libxslt-dev gcc libc-dev curl \
    && rm -rf /var/lib/apt/lists/*

COPY requirements.txt .
RUN pip install -r requirements.txt
RUN playwright install --with-deps chromium

COPY . .
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000", "--workers", "2"]

5. Conclusion & Ready-to-Use Workflow

You can manually wire this FastAPI microservice into your infrastructure following the architectural design and code above.

If you want the complete, production-ready implementation out of the box—including:

Pre-configured Docker Compose with Redis cache and persistent volume configurations
Playwright connection-pooling to avoid concurrency memory leaks
Rate-limiting middleware (slowapi) and health check probes
Complete test suites with synthetic fixtures and ready-to-import n8n orchestration workflows

You can grab the complete source repository directly:

Instant Access on Whop: Get the Microservice on Whop
Direct Download on Gumroad: Download on Gumroad — Use promo code EARLYBIRD at checkout for 20% off.

Building Smart Health API: A Production-Style REST API with CNN-Based Risk Prediction

Thu, 01 Oct 2026 15:25:23 +0000

By Priyadharshiny J — GitHub: priyadharshiny13

Overview

Smart Health API is a backend platform I built to explore how a real healthcare product might structure its API layer: role-based access for different user types, secure authentication, database migrations that don't break production, and a machine learning model wired into an async pipeline instead of blocking the request thread.

The result is a FastAPI service that lets Patients, Doctors, and Admins interact with the same system through different permission levels, and that returns CNN-based oral cancer risk scores without making the caller wait on model inference.

Stack

API layer: FastAPI
Database: MySQL, with SQLAlchemy ORM
Migrations: Alembic
Auth: JWT-based authentication with Role-Based Access Control (RBAC)
ML: TensorFlow CNN model for oral cancer risk prediction
Async processing: Celery + Redis
Infra: Docker, deployed toward AWS
CI/CD: GitHub Actions

Architecture Decisions

Why RBAC with three roles instead of a single user type?
Healthcare data access isn't uniform — a Patient should only see their own records, a Doctor needs read/write access to their assigned patients, and an Admin needs oversight without clinical permissions. I modeled this directly into the JWT claims and enforced it at the route-dependency level in FastAPI, rather than checking roles inside each endpoint's business logic. This keeps permission logic in one place and out of the individual handlers.

Why Alembic migrations instead of create_all()?
SQLAlchemy.create_all() is fine for a prototype, but it can't handle schema evolution — adding a column, renaming a table, backfilling data. Alembic gave the project versioned, reversible migrations, which is the same discipline a real production service needs the moment more than one person touches the schema.

Why Celery + Redis for the CNN inference?
Running a CNN prediction synchronously inside an HTTP request handler blocks the worker for however long inference takes, which doesn't scale under concurrent load. I moved prediction into a Celery task queue backed by Redis: the API accepts the image, enqueues the job, and returns a task ID immediately. The client polls (or would be pushed a webhook/notification in a fuller version) for the result. This separates the request/response cycle from the compute-heavy ML work.

A Real Debugging Story

Wiring up SQLAlchemy models across multiple modules (User, Patient, Doctor, Prediction) introduced circular import errors once relationships started referencing each other — Patient needed User, User needed Prediction, and Python's import system didn't like the cycle. The fix was restructuring model definitions to use string-based relationship references (relationship("Patient", back_populates=...)) instead of direct class imports, which lets SQLAlchemy resolve the relationship lazily at mapper-configuration time rather than at import time.

Small detail, but it's the kind of thing that only shows up once a schema has enough interrelated tables — and it's a good reminder that ORM relationship design needs the same intentionality as the schema itself.

What's Next

Add automated tests for the RBAC permission boundaries (currently manually verified)
Expose Celery task status through a WebSocket instead of polling
Add rate limiting on the prediction endpoint given its compute cost

Repo

Code and setup instructions: github.com/priyadharshiny13 — see the smart-health-api repository.

What If Full-Stack Features Were Installable?

Thu, 01 Oct 2026 07:36:17 +0000

NextAPI, and an experiment in reusing whole application capabilities instead of code.

Every developer knows the first week of a new project. Before a single line of product code, you wire up authentication, decide how roles work, connect a database, configure Docker and build the shell your pages will live in. Then, once the foundation is in place, you start on the features, and discover you are rebuilding the same team workspace, profile page and admin area you built on the last project.

Boilerplate solved the foundation. It never solved the features.

NextAPI is my attempt to solve both. It began as a Next.js and FastAPI starter and has grown into something more ambitious: a framework where a full-stack feature (its pages, its API, its database model, its permissions and its navigation) can be installed, verified, versioned and rolled back like a package.

This article walks through what that actually means, and why I think it matters.

Part One: A Foundation You Can Use Today

NextAPI Core is a complete full-stack application, ready in minutes. It stands entirely on its own. You never have to touch the module system to get value from it.

Out of the box, you get:

Capability	What it means in practice
Encrypted authentication	Credentials-based auth through NextAuth v5. Login and registration payloads are AES-256-CBC encrypted on the client before a signed JWT is ever issued.
Role-based access control	Admin, user and guest roles embedded in the JWT and enforced on both frontend and backend.
Machine-to-machine API access	API client tokens (`X-API-Key` / `X-API-Secret`) kept separate from user sessions, so integrations never borrow a person's login.
A modern async backend	FastAPI with Pydantic v2 validation and SQLAlchemy 2.0.
Two databases, one switch	SQLite by default with zero setup, or MongoDB with a single environment variable.
Web and native mobile from one codebase	The same frontend ships as Android and iOS apps through Capacitor, authenticating against the same JWT endpoints.
A configurable app shell	Sidebar or top navbar, chosen once.
Production-ready deployment	A Docker Compose stack with frontend, backend and an optional nginx reverse proxy with SSL.

Even setup has been designed to remove the usual failure points. Running npm run setup generates real secrets rather than placeholders, and writes the same encryption key to both the frontend and backend configuration. The two most common ways to break authentication by hand, a forgotten placeholder or keys that drift apart, simply cannot happen.

npm run setup
npm run dev

Frontend on port 3000, backend on port 8000, and you are building your product.

If you would rather start from a genuinely empty canvas, npm run init:blank permanently removes the demo pages, so there is no dead code to carry into production.

From here, the application is yours. Write your own routes, models and components. Install any npm or Python package. Change the architecture. NextAPI is not a hosted platform, and nothing about your application depends on anyone but you.

Part Two: The Problem Package Managers Never Solved

The package ecosystem is extraordinary. Need a Python library? Install it. Need a React component? There are thousands.

But what if you do not need a library? What if you need a feature?

Consider team management. It is not a component. It is a set of pages for teams, members and invitations; API endpoints behind each of them; database collections to store them; permissions governing who can do what; and navigation entries so users can find them.

Those pieces describe one capability. Yet the way we reuse software today scatters them across separate packages, separate copy-pastes and, most often, separate rewrites. Every copy starts drifting the moment it lands.

That led to the question at the heart of NextAPI:

What if the unit of reuse were the feature rather than the library?

Part Three: A Feature With a Contract

In NextAPI, a feature is a module, and every module is described by a single manifest. Here is a real one, lightly trimmed:

{
  "id": "ai-notes",
  "version": "1.0.0",
  "nextapiVersion": ">=1.0.0 <2.0.0",
  "requires": { "modules": ["profile-page@^1.0.0"] },
  "env": {
    "backend": [{ "key": "ANTHROPIC_API_KEY", "required": true, "secret": true }]
  },
  "dependencies": {
    "frontend": { "npm": { "react-markdown": "^9.0.0" } },
    "backend": { "pypi": { "anthropic": "^0.40.0" } }
  },
  "frontend": {
    "routes": [{ "path": "/notes", "protected": true, "label": "Notes" }]
  },
  "backend": {
    "router": { "module": "backend/router.py", "prefix": "/notes" },
    "collection": "module_ai_notes"
  },
  "functions": {
    "uses": ["auth.get_current_user", "profile.get_display_name"]
  }
}

Read it closely, because this is where the idea becomes concrete. In one file, this module declares:

the page it adds, that the page requires sign-in, and the label it shows in navigation;
the API router it contributes and the URL prefix it answers on;
the database collection it owns;
the npm and PyPI packages it needs;
the environment variables it requires, and which are secrets;
the other modules it depends on, with version ranges;
the specific functions it calls from those modules;
and the range of NextAPI versions it is compatible with.

A conventional package gives you code. This manifest gives the framework an understanding of a capability: what it is, what it needs and how it fits into the application around it. Everything else NextAPI does is built on that understanding.

Part Four: Two Commands, and What Really Happens

Installing a module needs no account:

nextapi add @alice/team-workspace
nextapi sync

add only records your intent in the project's lockfile. Nothing in your application changes.

sync is where the real work happens, and its defining principle is simple: nothing is written until the whole install has been proven safe. Before touching a single file, it:

resolves dependency order and checks for circular dependencies;
fetches any modules the new one depends on, automatically;
verifies that every function a module calls is actually provided by the module it depends on;
checks for route, backend package and database collection collisions.

If any check fails, the install is refused up front. An install is never left half-applied.

Only then does sync wire the feature into your real codebase:

your-app
├── app/team/page.tsx                                  new
├── backend/module_alice_team_workspace/router.py      new
├── backend/module_alice_team_workspace/models_mongo.py new
├── config/routes.ts                                   RBAC entry merged
└── .env                                               appended, your values untouched

The page appears in your sidebar or navbar automatically. The RBAC rules are merged into your configuration. The backend lands as its own isolated package.

Part Five: The Hard Problems, Solved in the Open

The idea is easy to state. What makes NextAPI worth taking seriously is how it handles the problems that make installable features genuinely difficult.

It joins your data instead of duplicating it

Suppose your application already has users, and you install a user-management module that also declares a users collection. A naive system creates a second, disconnected collection, and you now have two sources of truth about who can log in.

NextAPI detects the overlap. If the module's fields are compatible with your existing collection, sync offers to link the module to your real data instead:

'@alice/user-management' declares a "users" collection compatible with your
existing UserCollection. Link it instead of creating a separate collection? (y/N)

It goes further than matching field names:

Method adoption. If the module calls methods your collection class does not have yet, sync adds the module's implementations to your model. It is purely additive and never overwrites a method your application already relies on.
Real-data checks. A schema can match on paper and still not match reality. sync samples your actual MongoDB documents, and if a field your model declares as required is missing from existing records, it asks before relaxing it:

'users' collection: 'created_at' is declared required, but missing from
214/1,048 existing documents. Demote 'created_at' to optional in your
host's UserMongo model to match reality? (y/N)

Remembered decisions. Updates to a linked module re-link automatically. If a future version stops matching, it falls back safely and tells you exactly what happened.

When fields do not match, the module installs against its own collection and you receive a precise, field-by-field report of what did not line up, which is something concrete for the module's author to fix.

This is the difference between installing code into an empty project and integrating a feature into a living system.

Modules depend on capabilities, not just packages

Modules can declare the functions they provide and the functions they use. A support-chat module can call profile.get_display_name, provided by a profile module, and the registry confirms that capability exists before either module installs.

Package managers resolve graphs of libraries. NextAPI resolves a graph of application capabilities.

Names never collide

Two authors can both build a module with a /profile page and a profile collection. At install time, NextAPI automatically namespaces pages, backend code and database storage per module. Authors can write as though their module is the only one that will ever exist.

Versioned like real software

Versions follow semver and are immutable once published.
A bad release can be yanked from new installs without breaking anyone already using it.
Compatible version ranges are resolved to a single shared version automatically, and genuine conflicts are reported with both requirements named.
Stateless modules can opt into running multiple major versions side by side.
Stored data carries its own schemaVersion. Changing the shape of persisted documents requires publishing a normalizer that upgrades older documents on read, so no previously stored record ever becomes unreadable.

Every risky change is deliberate and reversible

Some modules replace an existing page rather than adding one: a custom login screen, a redesigned landing page. That requires an explicit acknowledgement written into the manifest itself, so it cannot be scripted past a prompt. Before anything is replaced, the original is captured as a full snapshot, and nextapi rollback /login restores it.

Files you have edited by hand since the last sync are detected and left alone. nextapi list flags drift, and nextapi remove will not discard your changes without --force.

Part Six: It Is Your Code

None of this turns your application into a black box.

After sync, a module's files are committed into your project as ordinary, readable source code, marked in clearly generated regions. You can edit them immediately. There is no runtime dependency on the registry. If the registry disappeared tomorrow, your application would keep running exactly as it does today.

That was a non-negotiable design goal. The registry distributes capabilities. It never owns them.

The registry at nextapi.app is where modules are published, discovered and installed. Building for it is designed to be as approachable as using it.

Build in the browser. Start from a working template and edit in a full code editor that understands TypeScript, JavaScript, Python and JSON, with errors marked on the exact line.
Build with AI. The AI Builder writes an entire module (manifest, backend, page and preview data) from a description. What sets it apart is discipline: it loads design standards before laying out a page, looks up a library's real documentation instead of guessing, lints its own output for accessibility issues such as contrast and reduced motion, and runs the same validation that gates every publish. Its output is identical in form to a hand-written module. The only difference is who typed it.
Publish with confidence. nextapi validate checks the schema, capabilities and file paths locally, and every publish is re-validated on the server. Each module must ship maintainer-facing implementation notes explaining what it assumes about the host application.
Share privately. Publish a private module and share it with specific people by username.
Fork with credit. Fork any public module to adapt it. The original author is recorded permanently and cannot be removed from the fork.

Part Eight: Core Stands on Its Own

This is worth stating plainly, because the registry can make the project appear more complex than it is.

You can use NextAPI Core purely as a full-stack foundation and ignore the module ecosystem entirely. The registry is a layer on top, not a requirement underneath:

                    Registry
                       |
             +---------+---------+
             |         |         |
          Module A  Module B  Module C
             |         |         |
             +---------+---------+
                       |
                  NextAPI Core
                       |
              +--------+--------+
              |                 |
           Next.js           FastAPI
              |                 |
              +--------+--------+
                       |
                    Database

NextAPI should be useful before the ecosystem exists. The registry should make it more powerful, never necessary.

What I Am Actually Building

I am not building another package manager, and I have no interest in replacing npm or PyPI. They solve a different problem, and they solve it well.

What interests me is moving one level higher. A library knows what functions it exports. A NextAPI module knows:

"I add these pages, and they require sign-in."
"I expose these API routes."
"I own this data, and this is the version of its shape."
"I need these permissions, packages and secrets."
"I depend on these capabilities from other modules."
"I belong in the navigation, here."

Once a framework has that information, it can do far more than copy code into a project. It can reason about how a feature fits into an application: whether it is safe, whether it conflicts, whether it should join existing data, and how to undo it.

Where Things Stand

NextAPI is open source under the MIT license and actively evolving. The foundation is solid, the module system already handles problems most tools never attempt, and plenty of hard work remains: richer migrations, broader host compatibility and a growing library of modules.

The underlying idea is one I believe is worth pursuing:

Instead of rebuilding the same full-stack features over and over, what if we could install the capability itself?

That is what NextAPI has become. Not just a starter kit, and not just a registry, but an attempt to move reusable software one step closer to the application itself.

Try it:

Source code: github.com/sup3rus3r/nextapi-core
Module registry and docs: nextapi.app
Support the project: GitHub Sponsors

Building a URL Shortener with FastAPI and SQLite — V1 Complete

Mon, 28 Sep 2026 16:49:18 +0000

After completing my Personal Expense Tracker, I started my fourth project: a URL Shortener. This was also my first web backend project, so the goal was to move from CLI applications into building a small web application and get more practical experience with FastAPI, SQLite, HTML, CSS, and Jinja2.

The result is a simple URL Shortener that takes a long URL, generates a short code, stores the mapping in SQLite, and redirects users to the original URL.

What Is a URL Shortener?

A URL shortener converts a long URL into a shorter link.

For example:

https://example.com/some/very/long/path/to/a/page

can become something like:

http://localhost:8000/aB72xK

When someone opens the shortened URL, the application looks up the short code in the database and redirects them to the original URL.

So the basic flow is:

Long URL
   ↓
Generate short code
   ↓
Store both in SQLite
   ↓
Return short URL
   ↓
User opens short URL
   ↓
Look up short code
   ↓
Redirect to original URL

Project Architecture

I kept the architecture intentionally simple for V1.

There are two main backend responsibilities:

FastAPI application

Handles the web routes, receives the submitted URL, generates the short code, displays the result, and performs the redirect.

SQLite database layer

Handles storing and retrieving the relationship between the short code and the original URL.

The database table contains:

urls
├── short_code
└── original_url

The short_code is the primary key because each shortened URL needs its own unique identifier.

Moving From API-Style Responses to a Web Interface

One of the interesting parts of this project was learning that FastAPI doesn't have to be used only for JSON APIs.

For the first stage of learning FastAPI, I worked with API-style routes and responses.

For this project, I wanted a simple user-facing interface instead.

So I used:

HTML for the page structure
CSS for basic styling
Jinja2 for server-side HTML rendering
FastAPI as the backend

The user submits a URL through the HTML form, FastAPI processes it, and Jinja2 renders the result back into the page.

I intentionally did not add JavaScript for V1. The goal was to understand the traditional server-rendered web application flow first.

Generating the Short Code

For the current version, the application generates a 6-character short code using letters and numbers.

The generated code is then stored together with the original URL.

For example:

short_code:   aB72xK
original_url: https://example.com/some/long/url

When /aB72xK is requested, the application searches for that short code and retrieves the original URL.

Redirecting the User

The redirect is the part that makes the application actually function as a URL shortener.

The application receives a request such as:

/aB72xK

It looks up aB72xK in SQLite.

If the code exists, FastAPI returns a redirect response to the stored original URL.

If the code doesn't exist, the application returns a not-found response.

This helped me understand that a shortened URL isn't just a smaller version of the original URL. It is an identifier that points to data stored by the application.

Keeping V1 Simple

One thing I wanted to maintain throughout this project was a limited scope.

The purpose of V1 was to learn the fundamental workflow, not to build a production-scale URL-shortening service.

Current V1 Scope

URL shortening
6-character short code generation
SQLite storage
URL redirection
Simple HTML + CSS interface
Jinja2 server-side rendering
Empty-input handling

That's where I decided to stop V1.

There are many features that could be added later, such as URL expiration, analytics, custom short codes, URL management, authentication, and more.

But adding all of them now would move the project away from its original learning goal.

What I Learned

This project helped me connect several concepts that I had previously learned separately.

I practiced:

Building a web application with FastAPI
Connecting FastAPI with SQLite
Designing a simple database structure
Using a database class to separate database operations
Generating unique identifiers
Handling redirects
Using Jinja2 templates
Connecting HTML forms with backend routes
Serving CSS through FastAPI
Organizing a small web application
Deploying the application as a web service

More importantly, I got a better understanding of how the frontend, backend, and database communicate with each other.

Project Structure

url-shortener/
├── main.py
├── database.py
├── requirements.txt
├── templates/
│   └── index.html
├── static/
│   └── style.css
├── .gitignore
├── LICENSE
└── README.md

What's Next?

V1 is now complete.

I want to keep the project available as a small working example of a FastAPI web application rather than continuously adding features without a specific learning goal.

Future versions could explore more advanced concepts when they become relevant to my learning path.

Final Thoughts

This project was a useful step from building command-line applications toward building web applications.

My previous projects helped me practice Python, OOP, CRUD operations, SQLite, and application structure. With the URL Shortener, I was able to bring those concepts together with FastAPI and a browser-based interface.

It's a small application, but it gave me practical experience with the complete basic flow:

Browser → FastAPI → SQLite → FastAPI → Browser

And that's exactly what I wanted from Project #4.

Project #4 — URL Shortener: V1 Complete.

Live Demo: https://url-shortener-k5ed.onrender.com/

Source Code: https://github.com/xDK0d3r/url-shortener

Continue Reading

I also wrote about this project on Dev.to, where I shared more about my learning experience, what I learned while building my first web backend project, and how this project fits into my overall development journey.

If you'd like to read that perspective, check it out here:

Read the Dev.to article →

How I Built and Monetized a Currency Exchange Rate API with FastAPI, Deployed it on Render, and Published it on RapidAPI.

Thu, 24 Sep 2026 16:03:18 +0000

Introduction:
In order to build passive income streams, I decided to publish APIs on RapidAPI. The idea is straightforward: build a useful API once, set up freemium pricing tiers, and earn recurring monthly income from subscribers.
In this post we will see how I built a Currency Exchange Rate API using FastAPI and Python, deployed it on Render, and published it on RapidAPI. I'll walk through the entire process including a debugging issue that cost me a few hours and might save you the same frustration.

The Tech Stack

FastAPI — chose this over Flask and Express because it auto-generates interactive API documentation at /docs out of the box, which is extremely useful when setting up and testing endpoints before publishing
Python — straightforward for API work, massive community support
ExchangeRate-API — free data source providing live rates for 160+ currencies, no scraping needed
Render — free tier hosting with simple GitHub deployment
RapidAPI — marketplace where developers discover and subscribe to APIs

The Three Endpoints

# 1. Get latest rates for any base currency
GET /latest?base=USD

# 2. Convert between two currencies
GET /convert?from=USD&to=INR&amount=100

# 3. List all supported currencies
GET /currencies

Here's the core conversion endpoint:

@app.get("/convert")
async def convert_currency(
    from_currency: str = Query(alias="from"),
    to_currency: str = Query(alias="to"),
    amount: float = Query(default=1.0)
):
    from_currency = from_currency.upper()
    to_currency = to_currency.upper()

    async with httpx.AsyncClient() as client:
        response = await client.get(
            f"{BASE_URL}/pair/{from_currency}/{to_currency}/{amount}"
        )
        data = response.json()
        return {
            "from": from_currency,
            "to": to_currency,
            "amount": amount,
            "rate": data["conversion_rate"],
            "converted": data["conversion_result"],
            "date": data["time_last_update_utc"]
        }

The Debugging Problem I faced
I originally built the API using Frankfurter (api.frankfurter.app) as the data source — it's free, requires no API key, and is backed by the European Central Bank. Perfect on paper.
The problem: when I tested with curl in the terminal, Frankfurter returned data perfectly. But when FastAPI made the same request using httpx, I kept getting this error:

{"detail": "Could not fetch rates for base currency: USD"}

After some debugging I ran this:

python -c "import urllib.request; print(urllib.request.urlopen('https://api.frankfurter.dev/latest').read())"

And got back:

urllib.error.HTTPError: HTTP Error 403: Forbidden

Frankfurter was blocking Python requests because they didn't include a browser-like User-Agent header. The server was rejecting anything that looked like a script.
I tried adding a User-Agent header to httpx but the issue persisted on my network. The clean fix was switching to ExchangeRate-API which has a proper free tier, returns consistent JSON, and works reliably with Python requests.
If you hit a 403 from a data source that works fine in the browser but fails in Python — check your User-Agent header first, and if that doesn't work, switch to a more developer-friendly data source.

Deploying on Render
Render's free tier is enough to get started. The setup takes about 5 minutes:

Push your code to GitHub
Connect the repo to Render → New Web Service
Set the start command: uvicorn main:app --host 0.0.0.0 --port 8000
Add your API key as an environment variable
Deploy

One important note — store your API key as an environment variable on Render, not hardcoded in your code. Use python-dotenv locally and os.getenv() to read it:

import os
from dotenv import load_dotenv
load_dotenv()
EXCHANGE_RATE_API_KEY = os.getenv("EXCHANGE_RATE_API_KEY")

The free tier has one limitation — cold starts. After 15 minutes of inactivity Render spins down your service and the first request takes 30-60 seconds to wake up. Upgrade to the $7/month starter plan once you have paying subscribers — your first subscriber covers the cost.

Publishing on RapidAPI
Once your API is live on Render, publishing on RapidAPI takes about 20 minutes:

Go to rapidapi.com/provider → Add New API
Add your Render URL as the Base URL
Add each endpoint with its query parameters
Set up freemium pricing tiers
Write a README and submit for review
RapidAPI review takes 24-48 hours. Once approved your API is discoverable by thousands of developers searching the marketplace.

Closing
The full API is live on RapidAPI — https://rapidapi.com/dhritibaruah20/api/currency-exchange-rate-api9. Free tier available with 100 requests/month.
I'm also building more APIs as part of a broader strategy to generate passive income as a developer.

Project LifeOps (Part 4): Executive Word (.docx) Reporting Engine and Multi-Sheet Excel (.xlsx)

Fri, 18 Sep 2026 14:06:04 +0000

In previous installments, we designed the FastAPI backend and Supabase database architecture, built the Glassmorphism React client, and engineered the interactive fitness, reading, cinema, and Kanban modules.

Yet in software engineering, one principle remains non-negotiable: data sovereignty.

Most subscription-based commercial apps commit the same calculated mistake: they allow users to enter data effortlessly for free, but when you want to export your records, you are met with obscure JSON dumps, truncated exports, or paywalls. If the company pivots or discontinues the service, your life telemetry is trapped in a closed silo.

When designing LifeOps, I established a golden rule: no recorded data would ever be held hostage. At any given moment, the user must be able to generate a beautifully styled, executive Word document (.docx) ready for printing or client presentation, a multi-sheet audit workbook in Excel (.xlsx) with dedicated tabs, and raw CSV backups with UTF-8 BOM ready for direct ingestion in PowerBI or spreadsheet tools without manual encoding fixes.

Best of all: implemented under a Zero-Disk in-memory architecture without saving temporary files to server disks. Let's see how it was engineered! 🚀

[!TIP]
Test the live app: You can generate and download your own reports in the production build of LifeOps at https://datalaria.com/apps/lifeops/.

🗺️ LifeOps Series Roadmap

To understand how every architectural layer fits together, this series spans 5 structured installments:

🟢 Part 1: Personal Operating System Architecture and FastAPI + Supabase Backend
🟢 Part 2: React Frontend with Glassmorphism, 360° Dashboard, and Design System
🟢 Part 3: Core Interactive Modules: Fitness, Library, Cinema, and Professional Kanban Board
🟢 Part 4 (This article): Executive Word (.docx) Reporting Engine and Multi-Sheet Excel (.xlsx) Export
🟢 Part 5: 24/7 Zero-Cost Cloud Deployment ($0/month), Mobile UX, and PWA

1. Zero-Disk Architecture: In-Memory RAM Generation with `io.BytesIO` 🧠⚡

Many online tutorials suggest a hazardous pattern for backend file downloads:

Write a temporary file to disk (e.g. /tmp/report_123.docx).
Populate the document.
Serve it over HTTP.
Schedule a background cronjob or script to delete it later.

In ephemeral cloud containers or serverless tiers (such as Render.com's free instances), this pattern is a recipe for failure:

Ephemeral storage is strictly constrained; multiple concurrent downloads will rapidly exhaust container disk space (Out of Disk Space crash).
If an unhandled exception occurs mid-execution, orphaned temporary files remain uncleaned.
Parallel requests can suffer race conditions or filename collisions if collision prevention is not meticulously handled.

In LifeOps, we built a Zero-Disk pipeline:

┌─────────────────────────────────────────────────────────────┐
│ 1. Frontend Request: POST /api/v1/reports/generate          │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ 2. FastAPI: Optimized relational query in Supabase          │
│    activities(*, workouts, books, films) + tasks + projects │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ 3. In-Memory Engine: python-docx / openpyxl                 │
│    doc.save(buffer) where buffer = io.BytesIO()             │
│    buffer.seek(0)                                           │
└──────────────────────────────┬──────────────────────────────┘
                               │
                               ▼
┌─────────────────────────────────────────────────────────────┐
│ 4. Direct Streaming HTTP Response:                          │
│    Response(content=buffer.getvalue(), media_type=docx)     │
│    Header: Content-Disposition: attachment; filename=...    │
└─────────────────────────────────────────────────────────────┘

The document is composed directly in memory RAM, buffered inside an io.BytesIO object, streamed to the client browser, and automatically reclaimed by Python's garbage collector once the response cycle ends. Zero disk I/O, zero file collision hazards, and maximum throughput.

2. Executive Word (.docx) Generation with `python-docx` 📄✨

For compiling Microsoft Word documents in Python, python-docx is the industry standard. However, default documents often appear rudimentary, featuring generic fonts and tables lacking inner cell padding.

To achieve an executive-grade aesthetic, I developed utility helpers that directly manipulate the underlying OpenXML elements (docx.oxml):

from docx import Document
from docx.shared import Inches, Pt, RGBColor
from docx.oxml import parse_xml
from docx.oxml.ns import nsdecls

# LifeOps Brand Palette
COLOR_PRIMARY_HEX = "0B0F17"    # Dark Obsidian
COLOR_EMERALD_HEX = "10B981"    # Emerald Accent
COLOR_BG_LIGHT_HEX = "F8FAFC"   # Soft Table Fill

def set_cell_background(cell, fill_hex: str):
    """Applies a solid background color to a Word table cell."""
    tcPr = cell._tc.get_or_add_tcPr()
    shd = parse_xml(f'<w:shd {nsdecls("w")} w:fill="{fill_hex}"/>')
    tcPr.append(shd)

def set_cell_margins(cell, top=100, bottom=100, left=150, right=150):
    """Sets inner cell padding (in twips, 20 twips = 1 pt)."""
    tcPr = cell._tc.get_or_add_tcPr()
    tcMar = parse_xml(
        f'<w:tcMar {nsdecls("w")}>'
        f'<w:top w:w="{top}" w:type="dxa"/>'
        f'<w:bottom w:w="{bottom}" w:type="dxa"/>'
        f'<w:left w:w="{left}" w:type="dxa"/>'
        f'<w:right w:w="{right}" w:type="dxa"/>'
        f'</w:tcMar>'
    )
    tcPr.append(tcMar)

2.1. Available Report Templates

The reporting service supports three purpose-built templates:

Monthly Integral Summary (monthly_summary): The complete 360° dossier. Aggregates monthly fitness distance, reading progress, cinema log, and active project deliverables.
Fitness Performance Dossier (sport_performance): Built for athletic analysis: total volume in kilometers, average paces, heart rate distributions, and Personal Best (PB) records.
Project Portfolio Status (project_status): Engineered for professional management: deliverable statuses, overdue deadlines, and the complete chronological progress log extracted from the JSONB comments column.

2.2. In-Memory Assembly

The entrypoint constructs the document and streams it directly to the buffer:

import io

def generate_docx_report(template_type: str, user_email: str, date_from, date_to, data: dict) -> io.BytesIO:
    doc = Document()

    # Uniform executive page margins (2 cm / 0.8 inches)
    for section in doc.sections:
        section.top_margin = Inches(0.8)
        section.bottom_margin = Inches(0.8)
        section.left_margin = Inches(0.8)
        section.right_margin = Inches(0.8)

    if template_type == "sport_performance":
        _build_sport_report(doc, user_email, date_from, date_to, data)
    elif template_type == "project_status":
        _build_project_report(doc, user_email, date_from, date_to, data)
    else:
        _build_monthly_integral_report(doc, user_email, date_from, date_to, data)

    buffer = io.BytesIO()
    doc.save(buffer)
    buffer.seek(0)
    return buffer

3. Multi-Sheet Excel (.xlsx) Workbooks with `openpyxl` 📊📗

Word dossiers provide polished executive summaries, but for quantitative analysis, pivot tables, or PowerBI models, the premier format is Excel (.xlsx).

Using openpyxl, we compile an audit workbook consolidating the user's entire cloud schema across 5 formatted thematic worksheets:

from openpyxl import Workbook
from openpyxl.styles import Font, PatternFill, Alignment, Border, Side
from openpyxl.utils import get_column_letter

def export_full_excel(user_id: str) -> io.BytesIO:
    wb = Workbook()
    wb.remove(wb.active)  # Drop default empty sheet

    # Corporate Styling
    header_fill = PatternFill(start_color="1E293B", end_color="1E293B", fill_type="solid")
    header_font = Font(name="Calibri", size=11, bold=True, color="FFFFFF")
    data_font = Font(name="Calibri", size=10)
    thin_border = Border(
        left=Side(style="thin", color="E2E8F0"),
        right=Side(style="thin", color="E2E8F0"),
        top=Side(style="thin", color="E2E8F0"),
        bottom=Side(style="thin", color="E2E8F0"),
    )

    sheets_config = [
        ("🏃 Sport & Fitness", _fetch_sport_data),
        ("📚 Book Library", _fetch_books_data),
        ("🎬 Cinema & TV", _fetch_films_data),
        ("📋 Tasks Kanban", _fetch_tasks_data),
        ("💼 Project Portfolio", _fetch_projects_data),
    ]

    for title, fetcher in sheets_config:
        ws = wb.create_sheet(title=title)
        ws.views.sheetView[0].showGridLines = True  # Gridlines always visible

        data = fetcher(user_id)
        if data:
            headers = [h.replace("_", " ").upper() for h in data[0].keys()]
            ws.append(headers)

            # Style Header Row
            for cell in ws[1]:
                cell.fill = header_fill
                cell.font = header_font
                cell.alignment = Alignment(horizontal="center", vertical="center")
            ws.row_dimensions[1].height = 24

            # Populate Rows with Cell Borders
            for row_idx, item in enumerate(data, start=2):
                ws.append(list(item.values()))
                for col_idx in range(1, len(headers) + 1):
                    c = ws.cell(row=row_idx, column=col_idx)
                    c.font = data_font
                    c.border = thin_border

            # Dynamic auto-fitting column widths
            for col in ws.columns:
                max_len = max(len(str(cell.value or "")) for cell in col)
                col_letter = get_column_letter(col[0].column)
                ws.column_dimensions[col_letter].width = max(max_len + 4, 12)

    buffer = io.BytesIO()
    wb.save(buffer)
    buffer.seek(0)
    return buffer

Professional Touches:

showGridLines = True: By default, Excel hides gridlines on worksheets featuring background styling. Forcing this flag ensures crisp readability.
Smart Auto-Fit Columns: Automatically calculates the longest string in each column and adds a 4-character safety buffer, eliminating truncated headers or numerical ### overflow errors.

4. CSV Backups: The Secret of UTF-8 BOM (`\ufeff`) 🛡️

For data engineers requiring raw tabular feeds for Python scripts or command-line pipelines, LifeOps exposes entity-level CSV downloads.

However, a notorious challenge exists: Microsoft Excel on Windows mishandles standard UTF-8 CSVs, converting accented characters and international letters (such as "Kilómetros" or "Diseño") into garbled symbols (mojibake), while frequently failing to split columns properly.

The elegant technical solution is prepending the UTF-8 Byte Order Mark (BOM) (\ufeff) and utilizing semicolon (;) delimiters:

import io
import csv

def export_entity_csv(entity: str, user_id: str) -> bytes:
    data = fetcher(user_id)
    output = io.StringIO()

    # 1. Prepend UTF-8 BOM so Excel opens accents natively
    output.write("\ufeff")

    if data:
        writer = csv.DictWriter(output, fieldnames=list(data[0].keys()), delimiter=";", quoting=csv.QUOTE_MINIMAL)
        writer.writeheader()
        for row in data:
            writer.writerow(row)

    return output.getvalue().encode("utf-8")

When users double-click the resulting file, Excel opens it perfectly without encoding dialogs, preserving accented strings and clean column separation.

5. Server Hardening: Anti-DoS Rate Limiting with `slowapi` ⏱️

Generating .docx documents and .xlsx workbooks requires significant CPU cycles and transient memory allocation. An automated script or abusive client sending 50 parallel requests could easily overwhelm Render's free container memory limits.

To protect uptime, we enforced IP and user-level rate limits with slowapi:

from slowapi import Limiter
from slowapi.util import get_remote_address

limiter = Limiter(key_func=get_remote_address)

# Strict rate limit for intensive Word (.docx) and Excel (.xlsx) compiles
@router.post("/generate")
@limiter.limit("10/minute")
def generate_report(request: Request, req: GenerateReportRequest, user = Depends(get_current_user)):
    ...

# Rate limit for lightweight CSV exports
@router.get("/export/csv")
@limiter.limit("20/minute")
def export_csv(request: Request, entity: str, user = Depends(get_current_user)):
    ...

If a client exceeds the threshold, FastAPI instantly responds with an HTTP 429 Too Many Requests, shielding backend memory for other users.

6. Frontend Center: Reports & Export UI (`ReportsPage.jsx`) 💻

In our React client, the /reports route provides an intuitive command center:

Interactive Template Cards: Clear previews explaining the target audience of each report.
Period Selectors: Instant shortcuts for Current Month, Previous Month, or custom date ranges.
Native Streaming Downloads: The browser handles streaming binary payloads via Blob APIs.

const response = await fetch(`${API_BASE_URL}/api/v1/reports/generate`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${token}`
  },
  body: JSON.stringify(requestPayload)
});

const blob = await response.blob();
const downloadUrl = window.URL.createObjectURL(blob);
const link = document.createElement('a');
link.href = downloadUrl;
link.download = filename;
link.click();
window.URL.revokeObjectURL(downloadUrl);

Conclusion & What's Next 🎯

With our reporting engine completed, LifeOps elevates from a web dashboard into an executive asset generator and portable data hub.

We have our cloud architecture, our dark-mode interface, our daily tracking modules, and our data export engine. Only one final milestone remains to conclude the series: production cloud deployment and mobile engineering.

In Part 5 (the final installment of this series), we will cover:

24/7 Zero-Cost Cloud Deployment ($0/month) on Render.com and Netlify, with proxy rewrites and automated SSL.
Ergonomic Mobile UX: Sticky Bottom Navigation Bar, touch-friendly Off-Canvas Drawer, and floating modales using React.createPortal.
Progressive Web App (PWA): Direct home-screen installation without app store friction.

References & Useful Links 🔗

🚀 Production Application: Try the reports download center at datalaria.com/apps/lifeops.
🌐 Production Swagger API: Reporting and export endpoints at lifeops-api.onrender.com/docs.
📄 python-docx: Official documentation at python-docx.readthedocs.io.
📊 openpyxl: Excel spreadsheet manipulation guide at openpyxl.readthedocs.io.
🛡️ SlowAPI: Rate limiting for FastAPI and Starlette at github.com/laurentS/slowapi.

See you in the final installment! Do you export your personal app data to Excel or Word? Share your workflow in the comments below. 👇

Project LifeOps (Part 3): Core Interactive Modules: Fitness, Library, Cinema, and Professional Kanba

Tue, 15 Sep 2026 06:12:43 +0000

In earlier installments, we engineered the foundational backbone of LifeOps: in Part 1 we designed the polymorphic PostgreSQL schema and modular FastAPI backend, and in Part 2 we brought the Glassmorphism Dark Mode design system and global 360° Dashboard to life.

Now comes the most defining phase of development: the day-to-day functional modules.

A personal operating system fails if it forces users into rigid input forms or scatters daily data across disconnected views. The challenge was articulating three completely disparate life areas under unified design and performance standards:

🏃 Health & Physical Fitness: Workout logging across sports with dynamic metrics (distance volume, calories, pace calculations, and Personal Bests).
📚 Intellectual Culture & Media: Book tracking with interactive reading progress bars and an entertainment catalog organized by streaming platform.
💼 Professional Execution: An agile 4-column Kanban board mapped to projects, equipped with a chronological progress log powered by PostgreSQL JSONB.

[!TIP]
Test the live app: You can explore the production build of LifeOps directly at https://datalaria.com/apps/lifeops/.

🗺️ LifeOps Series Roadmap

To understand how every architectural layer fits together, this series spans 5 structured installments:

🟢 Part 1: Personal Operating System Architecture and FastAPI + Supabase Backend
🟢 Part 2: React Frontend with Glassmorphism, 360° Dashboard, and Design System
🟢 Part 3 (This article): Core Interactive Modules: Fitness, Library, Cinema, and Professional Kanban Board
⚪ Part 4: In-Memory Word Dossiers (.docx) & Multi-Sheet Excel Engine (.xlsx)
⚪ Part 5: 24/7 Zero-Cost Cloud Deployment ($0/month), Mobile UX, and PWA

1. The UX Dilemma: Dual View Mode (Inspiring Cards vs. Synthesized Table) 🎴📊

When building data-intensive dashboards, designers face a classic user experience tradeoff:

The Grid / Cards View: Visually engaging, spacious, and inspiring. It highlights book covers, movie posters, and workout chips at a glance.
The Data Table View: Irreplaceable when auditing timestamps, comparing heart rates, or scanning through an entire month of logs without endless vertical scrolling.

Instead of forcing a single opinionated view, I built a persistent dual-mode toggle stored in localStorage:

const [viewMode, setViewMode] = useState(() => {
  return localStorage.getItem('lifeops_view_sport') || 'grid';
});

const handleViewChange = (mode) => {
  setViewMode(mode);
  localStorage.setItem('lifeops_view_sport', mode);
};

In the header of each module, two unobtrusive buttons with LayoutGrid and Table icons toggle the presentation mode instantly. Thanks to React and Vite's build architecture, view switches execute in sub-milliseconds without triggering redundant server roundtrips.

2. Fitness & Performance Module (`SportModule.jsx`) 🏃💨

The fitness module caters to multi-sport athletes practicing running, road cycling, gym strength sessions, and swimming.

┌────────────────────────────────────────────────────────────────────────┐
│  🏃 Sport & Fitness                    [ + Log Workout ]       [⊞|≡]   │
├─────────────────┬─────────────────┬─────────────────┬──────────────────┤
│ TOTAL DISTANCE  │ ACTIVE TIME     │ CALORIES        │ PERSONAL BESTS   │
│   142.5 km      │   18.4 hours    │   12,450 kcal   │    4 PBs 🏅      │
├─────────────────┴─────────────────┴─────────────────┴──────────────────┤
│                                                                        │
│ ┌───────────────────────────┐         ┌──────────────────────────────┐ │
│ │ 🏃 RUNNING         🏅 PB  │         │ 🚴 CYCLING                   │ │
│ │ Sunday Long Run           │         │ Mountain Pass Century Ride   │ │
│ │ 2026-09-10                │         │ 2026-09-08                   │ │
│ │ [📍 21.1 km] [⏱️ 1h 48m]  │         │ [📍 65.0 km] [⏱️ 2h 45m]     │ │
│ │ [🔥 1,420 kcal] [❤️ 152bpm]│        │ [🔥 1,890 kcal] [⛰️ +950m]    │ │
│ └───────────────────────────┘         └──────────────────────────────┘ │
└────────────────────────────────────────────────────────────────────────┘

2.1. Aggregated High-Level KPIs

Before rendering individual activity items, we compute cumulative totals using in-memory array reducers:

const totalKm = workouts.reduce((sum, act) => sum + (act.workout?.distance_km || 0), 0);
const totalMinutes = workouts.reduce((sum, act) => sum + (act.duration_minutes || 0), 0);
const totalCalories = workouts.reduce((sum, act) => sum + (act.workout?.calories || 0), 0);
const pbCount = workouts.filter((act) => act.workout?.personal_best).length;

2.2. Segregated FastAPI Payload

When an athlete records an exercise, the client dispatches a structured contract that FastAPI parses into the master table lifeops.activities and the child table lifeops.workouts:

const payload = {
  activity: {
    activity_type: 'sport',
    title: formData.title,
    date: formData.date,
    duration_minutes: parseInt(formData.duration_minutes),
    description: formData.notes,
  },
  workout: {
    workout_type: formData.workout_type, // 'running' | 'cycling' | 'gym'
    distance_km: parseFloat(formData.distance_km) || null,
    calories: parseInt(formData.calories) || null,
    avg_heart_rate: parseInt(formData.avg_heart_rate) || null,
    elevation_m: parseInt(formData.elevation_m) || null,
    personal_best: formData.personal_best,
    notes: formData.notes,
  },
};

This ensures shared attributes (dates, general durations, notes) remain globally indexable for the 360° Dashboard, while biometric attributes (elevation gain, heart rate, personal bests) reside in their specialized child table with cascading foreign key guarantees.

3. Culture & Media Tracking: Books & Cinema 📚🎬

For cultural tracking, the goal was leaving behind fragmented mobile notes in favor of an enriched visual library.

3.1. Interactive Reading Progress (`BooksModule.jsx`)

On each book card, we calculate page completion percentages in real time:

const percentage = b.pages_total > 0 
  ? Math.min(100, Math.round((b.pages_read / b.pages_total) * 100)) 
  : 0;

<div className="book-progress-wrapper">
  <div className="progress-info">
    <span>{b.pages_read} / {b.pages_total} pages</span>
    <span className="percentage-tag">{percentage}%</span>
  </div>
  <div className="progress-bar-bg">
    <div 
      className="progress-bar-fill" 
      style={{ 
        width: `${percentage}%`,
        background: percentage === 100 ? 'var(--accent-emerald)' : 'var(--grad-primary)'
      }} 
    />
  </div>
</div>

A status filter organizes titles into reading, completed, and wishlist, paired with an interactive 5-star rating system using lucide-react icons.

3.2. Streaming Media Catalog (`FilmsModule.jsx`)

The cinema module tracks movies, TV series, and documentaries cataloged by streaming provider (Netflix, HBO Max, Prime Video, Disney+, Cinema). Each entry logs release year, director, rating, and personal review notes, answering: "What were the best films I watched this past quarter?".

4. Professional Execution: The Kanban Board (`KanbanBoard.jsx`) 📋

For professional tasks, I implemented a full Kanban board featuring 4 columns reflecting agile task lifecycles:

📝 To Do (todo): Backlog tasks queued for upcoming execution.
⚡ In Progress (in_progress): Active work during the current sprint.
🔍 In Review (review): Tasks pending review, testing, or third-party feedback.
✅ Done (done): Completed deliverables.

┌──────────────────┬──────────────────┬──────────────────┬──────────────────┐
│ 📝 TO DO (3)     │ ⚡ IN PROGRESS (2)│ 🔍 IN REVIEW (1) │ ✅ DONE (8)      │
├──────────────────┼──────────────────┼──────────────────┼──────────────────┤
│ ┌──────────────┐ │ ┌──────────────┐ │ ┌──────────────┐ │ ┌──────────────┐ │
│ │ Refactor API │ │ │ Frontend UI  │ │ │ E2E Test Run │ │ │ DB Migration │ │
│ │ 🚨 Critical  │ │ │ 🟡 Medium    │ │ │ 🟢 Low       │ │ │ 2026-09-02   │ │
│ │ 📅 Sep 18    │ │ │ 💬 3 notes   │ │ │ 📅 Today     │ │ │ 💬 5 notes   │ │
│ │ [→ Move]     │ │ │ [←]      [→] │ │ │ [←]      [→] │ │ │ [← Move]     │ │
│ └──────────────┘ │ └──────────────┘ │ └──────────────┘ │ └──────────────┘ │
└──────────────────┴──────────────────┴──────────────────┴──────────────────┘

4.1. Optimistic UI Updates for Tactile Fluidity

When moving a task from in_progress to review, waiting for the entire roundtrip (browser → Render API → Supabase → response) introduces an undesirable delay of several hundred milliseconds.

To deliver an instantaneous tactile feel, we execute an optimistic state update in React:

const handleMoveTask = async (taskId, currentStatus, direction) => {
  const statusOrder = ['todo', 'in_progress', 'review', 'done'];
  const currentIndex = statusOrder.indexOf(currentStatus);
  const targetIndex = direction === 'next' ? currentIndex + 1 : currentIndex - 1;

  if (targetIndex < 0 || targetIndex >= statusOrder.length) return;
  const targetStatus = statusOrder[targetIndex];

  // 1. Instantaneous optimistic update

Why I Don't Put Tenant-Specific Validation in My FastAPI Endpoints

Thu, 10 Sep 2026 02:52:06 +0000

Multi-tenant applications have a way of turning simple endpoints into surprisingly complicated pieces of code.

At first, tenant-specific validation seems harmless.

You have two tenants with different limits, so you write something like:

if tenant == "acme":
    max_quantity = 100
elif tenant == "globex":
    max_quantity = 10

It works.

The problem isn't the first if.

The problem is what happens after there are ten more rules.

When the endpoint starts knowing too much

I prefer an endpoint to answer one main question:

What should the application do with this request?

I don't want the route handler to also be responsible for figuring out:

which tenant made the request
whether that tenant is active
what limits the tenant has
which validation rules apply
how those validation failures should be returned

None of those things are really the endpoint's job.

They are context and validation concerns.

Once those responsibilities start accumulating inside a route, even a small endpoint can become difficult to reason about.

FastAPI dependencies are a natural boundary

FastAPI's dependency injection provides a useful place to resolve tenant information.

For example, a request can contain:

X-Tenant-ID: globex

A dependency can turn that header into a strongly typed TenantConfig.

Now the rest of the request-processing pipeline doesn't need to repeatedly parse the header or look up the tenant.

But that still leaves an interesting problem.

The request body doesn't contain the information we need for every validation rule.

Some validation needs context

Consider a simple Pydantic model:

class OrderCreate(BaseModel):
    product_id: str = Field(..., min_length=1)
    quantity: int = Field(..., gt=0)

The model can determine that quantity=0 is invalid without knowing anything about the tenant.

But suppose:

acme   → maximum quantity = 100
globex → maximum quantity = 10

Now the validity of the same request depends on information outside the request body.

That's where Pydantic v2's validation context becomes useful.

Instead of hard-coding tenant names into the model, the application can pass the resolved tenant into validation:

OrderCreate.model_validate(
    payload,
    context={"tenant": tenant},
)

The validator can access that information through ValidationInfo.

The important part for me isn't the specific API. It's the separation of responsibilities:

FastAPI dependency
        ↓
Resolve tenant
        ↓
TenantConfig
        ↓
Pydantic validation
        ↓
Validated request
        ↓
Endpoint

The endpoint doesn't need to know how any of that happened.

But there's a trade-off

I don't think this pattern is automatically the right answer for every FastAPI application.

To make tenant information available before Pydantic validation, the example intentionally receives the request body as raw data and calls model_validate() itself.

That gives us the context we need, but we give up some of FastAPI's automatic request-body handling.

One noticeable consequence is OpenAPI documentation.

With a normal Pydantic request model, FastAPI can automatically generate a detailed request schema. With the raw-body approach, the generated request schema is less descriptive.

That's a real trade-off.

If automatically generated API documentation were the most important requirement, I'd investigate a different integration.

What I actually care about

The goal isn't to eliminate every if statement from an application.

It's to keep responsibilities somewhere they make sense.

I'd rather have an endpoint that looks like:

def create_order(
    ctx: TenantOrderContext = Depends(get_validated_order),
) -> OrderResponse:
    ...

than one that starts doing all of this:

def create_order(request, tenant):
    # resolve tenant
    # check tenant status
    # determine limits
    # validate request
    # handle validation failures
    # process order

The second approach isn't inherently broken.

It's just carrying more responsibility than the endpoint needs to.

The broader lesson

The interesting part of this exercise wasn't really multi-tenancy.

It was thinking about where validation gets its information from.

Some rules depend only on the object being validated.

Others depend on the context surrounding that object.

When validation depends on external context, putting everything inside the route handler is an easy solution. But it isn't necessarily the cleanest boundary.

FastAPI dependencies and Pydantic v2 validation context give you another option.

I built a small working example of this approach with FastAPI, Pydantic v2, and pytest, including tests for tenant-specific limits, invalid requests, inactive tenants, unknown tenants, and malformed payloads.

The complete implementation is available on GitHub.
{% embed https://github.com/MaybeSomeone-arc18/fastapi-multitenant-validation %}

Building a Real-Time Dashboard with FastAPI, WebSockets, and MySQL

Wed, 09 Sep 2026 08:42:41 +0000

I recently worked on a lightweight real-time dashboard built with FastAPI, WebSockets, and aiomysql.

The main goal was simple: retrieve live data from a MySQL database and push updates to the frontend in real time without relying on continuous polling.

This project provided a practical opportunity to explore asynchronous programming, WebSocket communication, and database integration using Python.

Project Overview

The application uses a FastAPI backend to communicate with a MySQL database and a WebSocket endpoint to deliver database updates to connected clients.

The overall architecture can be summarized as:

MySQL Database
      │
      ▼
   aiomysql
      │
      ▼
FastAPI Backend
      │
      ▼
  WebSocket
      │
      ▼
Frontend Dashboard

The WebSocket connection allows the server to push new data directly to the client, making the dashboard capable of displaying updates in real time.

What This Project Demonstrates

The project covers several important backend development concepts:

Setting up Python and the required dependencies
Building an asynchronous FastAPI backend
Connecting to MySQL using aiomysql
Implementing a WebSocket endpoint
Retrieving database records asynchronously
Sending live data to connected clients
Running the application with Uvicorn
Structuring a simple real-time backend application

Why Use WebSockets?

Traditional REST APIs generally follow a request/response model.

For example:

Client → Request → Server
Client ← Response ← Server

If the frontend needs updated information continuously, it may have to repeatedly send requests to the server.

This is commonly known as polling:

Client → Request
Server → Response

Client → Request
Server → Response

Client → Request
Server → Response

With WebSockets, the client establishes a persistent connection with the server:

Client ⇄ WebSocket Connection ⇄ Server

The server can then push new information to the client whenever it becomes available.

This makes WebSockets particularly useful for applications where data needs to be delivered quickly and continuously.

Potential Use Cases

This architecture can be useful for:

Real-time dashboards
Monitoring systems
Live administration panels
Student management systems
Record management applications
System status monitoring
Live data visualization
Notification systems

Documentation and Source Code

I created a complete guide covering the setup and implementation process, including:

Python installation
Required package installation
Project configuration
Server startup
Complete main.py implementation
FastAPI and WebSocket configuration

The GitHub repository also includes the documentation and source code for reference.

GitHub Repository

FastAPI WebSocket Real-Time Dashboard - GitHub Repository

The repository contains:

Complete Guide (PDF)
Source Code (main.py)

Key Technologies

Technology	Purpose
Python	Backend programming
FastAPI	Asynchronous web framework
WebSockets	Real-time client-server communication
aiomysql	Asynchronous MySQL connectivity
MySQL	Database
Uvicorn	ASGI server

Final Thoughts

This project was a useful exercise in combining asynchronous programming, database connectivity, and real-time communication into a practical backend application.

FastAPI and WebSockets provide a straightforward foundation for building applications where data needs to move between the server and client with minimal delay.

I look forward to extending this project with features such as authentication, multiple connected clients, automatic database change detection, improved error handling, and a more advanced frontend dashboard.

If you are working with FastAPI or real-time applications, I'd be interested to hear about your projects and approaches.

Also Published On

This article is also available on the following platforms:

LinkedIn: Read on LinkedIn
Medium: Read on Medium
AWS: Read on AWS
DEV Community: Read on DEV Community

Coding Period Has Started(WEEK-1)

Tue, 08 Sep 2026 21:14:31 +0000

Progress I have made in this week:

Created a ArtifactManager object which hooks into the OHIFViewer and
gets access to the cornerstone tools.
Created a FindSimilarArtifacts tool which gets the coordinates from
the rectangle ROI and performs the next steps.
Drafted the EventListener which handles asynchronous response
payloads with the FastAPI backend.

Things for next week:

Extracting DICOM Instance UID from the Orthanc viewer state to
properly route images to the AI model.
Creating a JSON payload of the exact ROI coordinates and routing it
to the backend.
Drafting a Microservice Architecture for the FastAPI server.

FastAPI Authentication with UserHarbor

Mon, 07 Sep 2026 20:38:47 +0000

This tutorial shows how to connect UserHarbor directly to a FastAPI application and build a complete authentication flow step by step.

UserHarbor is a framework-agnostic Python library for user accounts, authentication, sessions, password recovery, and roles and permissions. It keeps those security rules in the application layer while leaving HTTP routing, persistence, and email delivery to integrations. For more information about UserHarbor and its design, see the official documentation.

Note: For most FastAPI applications, prefer the ready-made userharbor-fastapi adapter. It provides the router, dependencies, schemas, and HTTP error mapping shown in this tutorial.

This tutorial builds the same ideas step by step.

You will create a small FastAPI application that uses UserHarbor directly for:

user registration
email verification
login
bearer session authentication
current-user dependencies
password reset
password change
account deletion
logout
role and permission checks

The goal is to show how the pieces fit together. UserHarbor owns the account rules, password hashing, token generation, token hashing, session validation, and role checks. FastAPI owns HTTP routing, request parsing, response models, and dependency injection.

Install dependencies

Create a virtual environment, then install FastAPI, UserHarbor, and a storage adapter:

pip install "fastapi[standard]"
pip install userharbor
pip install userharbor-sqlalchemy

This tutorial uses the SQLAlchemy store and a small console email sender. In a real application, use your normal database configuration and an email sender such as userharbor-smtp.

Create `main.py`

Start with the imports and application setup:

from typing import Any

from fastapi import Depends, FastAPI, HTTPException, status
from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
from pydantic import BaseModel
from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker
from userharbor import UserHarbor
from userharbor.exceptions import (
    InvalidCredentialsError,
    InvalidEmailError,
    InvalidPasswordResetTokenError,
    InvalidPermissionError,
    InvalidRoleError,
    InvalidSessionTokenError,
    InvalidUsernameError,
    InvalidVerificationTokenError,
    PermissionDeniedError,
    UnknownPermissionError,
    UnknownRoleError,
    UnverifiedUserError,
    UserHarborError,
    WeakPasswordError,
)
from userharbor_sqlalchemy import SQLAlchemyUserStore


app = FastAPI()
bearer = HTTPBearer(auto_error=False)

HTTPBearer(auto_error=False) lets your code decide exactly how to turn missing or invalid credentials into HTTP responses.

Add an email sender

UserHarbor calls an EmailSender when it needs to send verification tokens, password reset tokens, and account notifications.

For the tutorial, print those messages to the terminal:

class ConsoleEmailSender:
    def send_verification(
        self,
        username: str,
        email: str,
        verification_token: str,
    ) -> None:
        print(f"Verify {username} at {email}: {verification_token}")

    def send_password_reset(
        self,
        username: str,
        email: str,
        reset_token: str,
    ) -> None:
        print(f"Reset password for {username} at {email}: {reset_token}")

    def send_email_verified(self, username: str, email: str) -> None:
        print(f"Email verified for {username} at {email}")

    def send_password_changed(self, username: str, email: str) -> None:
        print(f"Password changed for {username} at {email}")

    def send_account_deleted(self, username: str, email: str) -> None:
        print(f"Account deleted for {username} at {email}")

In production, replace this with an implementation that sends real email.

Configure UserHarbor

Create the SQLAlchemy store, create the tables, and pass the store and email sender to UserHarbor:

engine = create_engine("sqlite:///users.db")
SessionLocal = sessionmaker(bind=engine)

store = SQLAlchemyUserStore(SessionLocal)
store.metadata.create_all(engine)

harbor = UserHarbor(
    secret_key="change-this-secret-key",
    store=store,
    email_sender=ConsoleEmailSender(),
)

The FastAPI application never handles password hashing or token hashing. UserHarbor does that before data reaches the store.

Define request and response models

Use Pydantic models for the HTTP layer:

class RegisterRequest(BaseModel):
    username: str
    email: str
    password: str


class LoginRequest(BaseModel):
    username: str
    password: str


class VerifyEmailRequest(BaseModel):
    token: str


class PasswordResetRequest(BaseModel):
    email: str


class PasswordResetConfirmRequest(BaseModel):
    token: str
    new_password: str


class ChangePasswordRequest(BaseModel):
    old_password: str
    new_password: str


class DeleteAccountRequest(BaseModel):
    password: str


class TokenResponse(BaseModel):
    access_token: str
    token_type: str = "bearer"


class PublicUser(BaseModel):
    username: str
    email: str
    verified: bool

These models are not part of UserHarbor. They are your HTTP contract.

Map UserHarbor errors to HTTP errors

UserHarbor raises domain exceptions. Your web layer should translate them into HTTP responses:

ERROR_CODES: dict[type[UserHarborError], str] = {
    InvalidCredentialsError: "invalid_credentials",
    InvalidEmailError: "invalid_email",
    InvalidPasswordResetTokenError: "invalid_password_reset_token",
    InvalidPermissionError: "invalid_permission",
    InvalidRoleError: "invalid_role",
    InvalidSessionTokenError: "invalid_session_token",
    InvalidUsernameError: "invalid_username",
    InvalidVerificationTokenError: "invalid_verification_token",
    PermissionDeniedError: "permission_denied",
    UnknownPermissionError: "unknown_permission",
    UnknownRoleError: "unknown_role",
    UnverifiedUserError: "unverified_user",
    WeakPasswordError: "weak_password",
}


def error_code(error: UserHarborError) -> str:
    for error_type, code in ERROR_CODES.items():
        if isinstance(error, error_type):
            return code
    return "userharbor_error"


def status_code(error: UserHarborError) -> int:
    if isinstance(error, (InvalidCredentialsError, InvalidSessionTokenError)):
        return status.HTTP_401_UNAUTHORIZED
    if isinstance(error, (PermissionDeniedError, UnverifiedUserError)):
        return status.HTTP_403_FORBIDDEN
    if isinstance(error, (UnknownPermissionError, UnknownRoleError)):
        return status.HTTP_404_NOT_FOUND
    if isinstance(error, InvalidUsernameError) and "already exists" in str(error):
        return status.HTTP_409_CONFLICT
    return status.HTTP_400_BAD_REQUEST


def to_http_error(error: UserHarborError) -> HTTPException:
    return HTTPException(
        status_code=status_code(error),
        detail={
            "detail": str(error) or error.__class__.__name__,
            "code": error_code(error),
        },
        headers={"WWW-Authenticate": "Bearer"}
        if isinstance(error, InvalidSessionTokenError)
        else None,
    )

This keeps authentication failures, authorization failures, and validation errors distinct.

Register users

The registration endpoint parses JSON, calls harbor.register(), and returns a neutral response:

@app.post("/auth/register", status_code=status.HTTP_201_CREATED)
def register(request: RegisterRequest) -> dict[str, str]:
    try:
        harbor.register(
            username=request.username,
            email=request.email,
            password=request.password,
        )
    except UserHarborError as error:
        raise to_http_error(error) from error
    return {"detail": "User registered"}

UserHarbor validates the username, email, and password. It creates the user, stores only the password hash, stores only the verification token hash, and calls the email sender with the raw verification token.

Verify email addresses

Copy the verification token printed by ConsoleEmailSender and send it to this endpoint:

@app.post("/auth/verify-email")
def verify_email(request: VerifyEmailRequest) -> dict[str, str]:
    try:
        harbor.verify_email(request.token)
    except UserHarborError as error:
        raise to_http_error(error) from error
    return {"detail": "Email verified"}

After verification, the user can log in.

Call harbor.login() and return the session token in a bearer-compatible response:

@app.post("/auth/login", response_model=TokenResponse)
def login(request: LoginRequest) -> TokenResponse:
    try:
        session_token = harbor.login(request.username, request.password)
    except UserHarborError as error:
        raise to_http_error(error) from error
    return TokenResponse(access_token=session_token)

The raw session token is returned to the client once. UserHarbor stores a hash of it through the configured store.

Clients should send the token on later requests:

Authorization: Bearer <session-token>

Create current-user dependencies

Now create the dependency that reads the bearer token and asks UserHarbor for the current user:

def get_session_token(
    credentials: HTTPAuthorizationCredentials | None = Depends(bearer),
) -> str:
    if credentials is None:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Missing bearer token",
            headers={"WWW-Authenticate": "Bearer"},
        )
    return credentials.credentials


def get_current_user(token: str = Depends(get_session_token)) -> Any:
    try:
        return harbor.get_current_user(token)
    except UserHarborError as error:
        raise to_http_error(error) from error

This is the main connection between FastAPI security dependencies and UserHarbor session validation.

Protect a route

Use Depends(get_current_user) in any route that requires authentication:

def serialize_user(user: Any) -> PublicUser:
    return PublicUser(
        username=user.username,
        email=user.email,
        verified=user.verified,
    )


@app.get("/auth/me", response_model=PublicUser)
def me(user: Any = Depends(get_current_user)) -> PublicUser:
    return serialize_user(user)

If the token is missing, invalid, expired, or points to a deleted user, UserHarbor rejects it.

Logout

Logout removes the current session token:

@app.post("/auth/logout")
def logout(token: str = Depends(get_session_token)) -> dict[str, str]:
    try:
        harbor.logout(token)
    except UserHarborError as error:
        raise to_http_error(error) from error
    return {"detail": "Logged out"}

To remove all sessions for the current user:

@app.post("/auth/logout-all")
def logout_all(token: str = Depends(get_session_token)) -> dict[str, str]:
    try:
        harbor.logout_all(token)
    except UserHarborError as error:
        raise to_http_error(error) from error
    return {"detail": "Logged out from all sessions"}

Password reset

Password reset is split into two routes. The first route sends a reset token if the email belongs to a user:

@app.post("/auth/password-reset/request")
def request_password_reset(request: PasswordResetRequest) -> dict[str, str]:
    try:
        harbor.send_password_reset(request.email)
    except UserHarborError as error:
        raise to_http_error(error) from error
    return {"detail": "Password reset email sent"}

UserHarbor returns neutrally for unknown email addresses, helping reduce email enumeration.

The second route accepts the reset token and the new password:

@app.post("/auth/password-reset/confirm")
def confirm_password_reset(request: PasswordResetConfirmRequest) -> dict[str, str]:
    try:
        harbor.reset_password(
            new_password=request.new_password,
            reset_token=request.token,
        )
    except UserHarborError as error:
        raise to_http_error(error) from error
    return {"detail": "Password reset"}

After a successful reset, UserHarbor removes all sessions for that user.

Password change

Password change requires an existing session and the current password:

@app.post("/auth/password/change")
def change_password(
    request: ChangePasswordRequest,
    token: str = Depends(get_session_token),
) -> dict[str, str]:
    try:
        harbor.change_password(
            old_password=request.old_password,
            new_password=request.new_password,
            session_token=token,
        )
    except UserHarborError as error:
        raise to_http_error(error) from error
    return {"detail": "Password changed"}

UserHarbor invalidates all sessions after a successful password change.

Delete accounts

Account deletion should require both a valid session and the current password:

@app.delete("/auth/account")
def delete_account(
    request: DeleteAccountRequest,
    token: str = Depends(get_session_token),
) -> dict[str, str]:
    try:
        harbor.delete_account(
            password=request.password,
            session_token=token,
        )
    except UserHarborError as error:
        raise to_http_error(error) from error
    return {"detail": "Account deleted"}

UserHarbor removes all sessions before deleting the user and then calls the email sender with an account-deleted notification.

Add role and permission dependencies

Create a dependency factory for permissions:

def require_permission(permission: str):
    def dependency(token: str = Depends(get_session_token)) -> Any:
        try:
            return harbor.require_permission(token, permission)
        except UserHarborError as error:
            raise to_http_error(error) from error

    return dependency

Use it on protected routes:

@app.get("/admin/users")
def list_users(
    user: Any = Depends(require_permission("users.read")),
) -> dict[str, str]:
    return {"detail": f"{user.username} can read users"}

Before this can succeed, the permission and role must exist and the user must have the role:

harbor.roles.create("admin")
harbor.permissions.create("users.read")
harbor.roles.grant_permission("admin", "users.read")
harbor.grant_role("jane", "admin")

In a real application, put that setup in migrations, admin commands, or an internal admin interface.

Production hardening checklist

This tutorial keeps everything in one file so the flow is easy to inspect. For a real application:

load secret_key, database URLs, and SMTP credentials from environment variables or a secret manager
use a long random secret_key and rotate it carefully, because it is used for token hashing
serve the API only over HTTPS
replace ConsoleEmailSender with a real email sender
use migrations instead of store.metadata.create_all(engine) at runtime
decide where roles and permissions are created, such as migrations or admin commands
keep bearer tokens out of logs
configure CORS explicitly if a browser frontend calls the API
add rate limiting around login, password reset, and verification resend
return neutral responses for account discovery-sensitive flows
write tests for successful flows and for each mapped error response

Run the app

Run the application:

fastapi dev main.py

Open the interactive docs:

http://127.0.0.1:8000/docs

Then try this flow:

Call POST /auth/register
Copy the verification token printed in the terminal
Call POST /auth/verify-email
Call POST /auth/login
Copy the returned access_token
Send it as Authorization: Bearer <token>
Call GET /auth/me

What you built

You now have a FastAPI application that uses UserHarbor directly.

FastAPI handles:

routing
request parsing
response models
OpenAPI documentation
dependency injection
HTTP status codes

UserHarbor handles:

account validation
password hashing
token generation
token hashing before storage
email verification
session validation
password reset and password change flows
role and permission checks

This is the same boundary used by the userharbor-fastapi adapter. The adapter simply packages this wiring so applications do not have to repeat it.

Building Role-Based Student, Teacher, and Admin Experiences in EchoEd

Wed, 26 Aug 2026 21:28:49 +0000

A role-based product should involve more than hiding navigation links.

Students, teachers, and platform administrators have different goals, data needs, privacy constraints, and consequences attached to their actions. EchoEd’s recent UI/UX work separates these roles into three
canonical product areas:

/learn for students
/teach for teachers
/admin for platform administrators

The attached demo videos show each experience in its current form.

Student Learn

{% embed https://www.youtube.com/watch?v=cch47qSHPHY %}

The Student experience prioritizes continuation over navigation complexity.

The /learn home composes existing course, progress, badge, certificate, and learner-product APIs to show:

The next governed learning action
Current courses and progress
Available learning
Progress summaries
Badges and certificates

Course overviews use a reusable curriculum component for units and lessons. Lesson entry still goes through the existing start-course and progress APIs, so the UI cannot bypass backend sequencing rules.

Final assessment submissions use a shared confirmation dialog. Lesson completion exposes saving and failure states rather than optimistically assuming persistence.

No backend contracts were changed for the Student phase.

Teacher Teach

{% embed https://www.youtube.com/watch?v=t3wBziH96N4 %}

The Teacher experience introduces a canonical route family:

/teach
/teach/classes
/teach/classes/:id
/teach/curriculum
/teach/courses/:courseId/preview
/teach/assignments
/teach/learners/:learnerId

The Teacher home focuses on classes, learner progress, and curriculum. Class detail composes existing section APIs into overview, roster, assignment, progress, and discussion views.

Learner detail is scoped through class-roster context. Assignment creation uses confirmation and preserves form values after API failures.

The UI does not expose persistent feedback, manual review, or destructive discussion moderation because those workflows do not yet have sufficiently scoped backend contracts.

Platform Admin

{% embed https://www.youtube.com/watch?v=Gj_T4a8uiiw %}

The Admin experience uses canonical routes for overview, users, organizations, courses, badges, and reports.

Important implementation decisions include:

User lists omit unnecessary fields.
Role mutations wait for API confirmation before updating the UI.
Self-role changes and self-deletion are blocked in the interface.
Destructive actions use exact consequence language.
Organization visibility remains constrained by current membership-scoped APIs.
Course oversight does not grant Content Studio authoring.
Super Admin capabilities are based on verified authorization, not role-name assumptions.
Unsupported moderation and lifecycle controls remain absent.

During seeded browser testing, the user-detail flow exposed a backend issue: FastAPI accepted the user ID as a string while SQLAlchemy compared it with a UUID column.

The repair typed detail and update parameters as uuid.UUID. We also moved the static /api/users/students route before /api/users/{user_id} so the dynamic route could not shadow it.

Regression tests now cover both behaviors.

Shared UX and Accessibility

All three areas reuse the same production foundations:

Semantic design tokens
Role-aware shell navigation
Route guards
Shared loading and state components
Confirmation dialogs with focus trapping and restoration
Keyboard-operable controls
Visible focus indicators
Reduced-motion behavior
Semantic desktop tables
Stacked mobile record layouts
Legacy deep-link compatibility

The frontend improves presentation and workflow clarity, but backend authorization remains authoritative.

Current Verification

Frontend unit tests: 245 passing
Backend tests: 224 passing
Seeded Playwright scenarios: 3 passing
Production build: passing
Strict OpenSpec validation: passing

The Playwright suite currently covers the seeded Student workflow, the Platform Admin workflow, and rejection of an unauthorized Student deep link into Admin.

Known Gaps

Several workflows need stronger backend contracts before the UI can safely support them:

Persistent teacher feedback
Scoped teacher review
Authenticated discussion moderation
Platform-wide organization oversight
Account suspension and restoration
Administrative audit events
Badge lifecycle management
Explicit Super Admin permission inheritance
Privacy-minimized Admin user response schemas

These are documented gaps, not frontend placeholders.

Community Review

I would value feedback from people working across education and software:

Do the boundaries between Learn, Teach, and Admin match real responsibilities?
Which Teacher information should be visible at class level versus learner level?
What information should a platform administrator never see in a broad user list?
Which workflows should receive deeper screen-reader and keyboard testing?
Which backend gap would you prioritize before expanding the next UI phase?

The Student, Teacher, and Platform Admin production phases are complete for EchoEd’s currently supported APIs.

The full UI/UX overhaul is still underway. Content Studio, organization-admin self-service, Community, parent, and viewer experiences remain outside these completed phases.

Building UserHarbor: Framework-Agnostic User Management for Python

Mon, 17 Aug 2026 12:31:04 +0000

User management is one of those problems that rarely feels difficult enough to deserve much attention.

Until you implement it for the fifth time.

Registration, login, sessions, email verification, password resets, password changes, account deletion, roles, permissions — none of these features are particularly unusual. But almost every application needs some combination of them, and the implementation often ends up tightly coupled to whatever framework, ORM, or infrastructure the project happened to use at the time.

That was the problem that led me to build UserHarbor.

UserHarbor is a framework-agnostic Python library for user account management. The goal is not to build another web framework or a complete identity platform. Instead, it provides a small domain-level API for common account operations while leaving HTTP, databases and email delivery to separate integrations.

Since I first wrote about the project, the interesting part has increasingly become not just the authentication API itself, but the boundary between the core and its integrations.

The problem I wanted to solve

Imagine building two applications.

One uses:

FastAPI
SQLAlchemy
PostgreSQL
SMTP

Another uses:

Flask
MongoDB
an external email API

The user-management rules are mostly the same.

A password still needs to be validated and hashed. A verification token still needs to expire. Password reset tokens still need to be protected. Sessions need to be created and invalidated. Roles and permissions need to be checked.

But in many libraries these rules are mixed together with database models, HTTP handlers or framework-specific abstractions.

I wanted the opposite.

The core should know what should happen, but not necessarily how the application stores or transports the data.

That leads to an architecture that looks roughly like this:

Application / Framework
        │
        ▼
    UserHarbor
        │
        ├── UserStore
        │       └── database / ORM / custom backend
        │
        └── EmailSender
                └── SMTP / API / custom provider

The core owns things such as registration, validation, password hashing, token generation, token hashing, session handling and authorization rules.

The adapters own infrastructure.

A small domain-level API

UserHarbor currently handles the common account lifecycle:

user registration
email verification
login
sessions
logout from one or all sessions
password change
password reset
account deletion
roles and permissions

It deliberately does not expose HTTP endpoints itself.

That means code using the core can look like this:

user = harbor.register(
    username="jane",
    email="*Emails are not allowed*",
    password="StrongPassword123!",
)

harbor.verify_email(verification_token)

session_token = harbor.login(
    username="jane",
    password="StrongPassword123!",
)

current_user = harbor.get_current_user(session_token)

The same UserHarbor instance can be used from FastAPI, Flask, Django, a CLI application or something that does not expose HTTP at all.

Authorization follows the same idea:

harbor.roles.create("admin")
harbor.permissions.create("users.delete")

harbor.roles.grant_permission(
    "admin",
    "users.delete",
)

harbor.grant_role("jane", "admin")

if harbor.has_permission(session_token, "users.delete"):
    delete_user()

Or, if access should be enforced:

user = harbor.require_permission(
    session_token,
    "users.delete",
)

UserHarbor implements simple role-based access control, but leaves application-specific authorization policy outside the core. It intentionally does not try to become a general policy engine.

Framework-agnostic does not mean framework-unfriendly

One thing I wanted to avoid was making framework independence come at the cost of developer experience.

For example, there is an official userharbor-fastapi integration.

Instead of manually writing authentication routes and dependencies, a FastAPI application can configure UserHarbor and attach the adapter:

from fastapi import FastAPI
from userharbor import UserHarbor
from userharbor_fastapi import UserHarborFastAPI

harbor = UserHarbor(
    secret_key="your-secret-key",
    store=store,
    email_sender=email_sender,
)

auth = UserHarborFastAPI(harbor)

app = FastAPI()
app.include_router(
    auth.router,
    prefix="/auth",
    tags=["auth"],
)

The adapter provides the framework-specific layer: routers, request schemas, bearer authentication dependencies, error mapping and helpers for requiring roles or permissions.

The important part is that FastAPI still does not leak into the UserHarbor core.

You can replace the web framework without replacing the account-management logic.

The harder problem: what does it mean to implement `UserStore`?

Originally, separating persistence behind a UserStore interface seemed like the obvious solution.

Define an interface, implement the methods, and now SQLAlchemy, MongoDB, Redis or anything else can provide storage.

But there is a subtle problem.

Matching method signatures does not mean two storage implementations behave the same way.

Consider a password reset token.

Should creating a new token remove an older token?

What happens when a user is deleted?

Should their sessions disappear automatically?

What should happen if a transaction fails halfway through a password change?

Should deleting something that no longer exists raise an error?

These behaviors are part of the storage contract even though Python's type system cannot express them.

This became one of the most important changes in UserHarbor 0.7.0.

Turning the adapter contract into executable tests

UserHarbor now ships a reusable contract test suite for UserStore implementations.

An adapter can import the complete suite:

# tests/test_user_store_contract.py

from userharbor.testing.user_store_contract import *

Then it only needs to provide a clean store:

import pytest


@pytest.fixture
def user_store():
    store = create_user_store()

    try:
        yield store
    finally:
        dispose_user_store(store)

The same tests can then run against SQLAlchemy, an in-memory implementation, or a completely different persistence backend.

Version 0.7.0 introduced 57 reusable contract tests covering users, password hashes, verification tokens, password reset tokens, sessions, roles, permissions, relationships and transaction behavior.

This changes the meaning of an adapter.

A compatible UserStore no longer just claims to implement an interface. It can demonstrate that it follows the behavioral semantics expected by the core.

For example, the contract specifies that:

usernames and email addresses are unique
user creation and the initial verification token are atomic
a new verification token replaces the previous one
a new password reset token replaces the previous one
deleting a user removes their sessions and related tokens
repeated relationship assignments are idempotent
deleting roles and permissions removes their assignments
successful transactions commit
failed transactions roll back
nested transactions participate in the outer transaction

These details are easy to overlook when implementing another backend, and they are exactly the type of differences that can produce authentication bugs which only appear much later.

For me, this was an important step in the architecture: the abstraction is now described not only by Python protocols and documentation, but also by executable behavior.

A template for building new storage adapters

To make that process easier, I also created userharbor-inmemory.

It is a minimal in-memory UserStore implementation that passes the complete storage contract.

It serves two purposes.

First, it is useful for tests and examples where a real database is unnecessary.

Second, the repository itself can be used as a template for creating new storage integrations. A developer can start with a working implementation and passing contract tests, replace the in-memory backend incrementally, and continuously verify that the new adapter still behaves correctly.

The idea is that creating something like a future database adapter should mostly become:

working UserStore template
        │
        ▼
replace persistence implementation
        │
        ▼
run shared contract tests
        │
        ▼
add backend-specific tests

instead of reverse-engineering the expected behavior from the core implementation.

Keeping security behavior inside the core

Another important architectural boundary is that storage adapters never receive raw tokens for persistence.

UserHarbor generates the raw verification, reset and session tokens, but hashes them before passing them to UserStore.

The raw token is given only to the part of the application that needs it — for example, to an email sender or to the user after login.

The database stores the hash.

The core also owns behavior such as token expiration and session validation.

Sensitive account-discovery flows are designed to return neutral responses where appropriate. For example, requesting a password reset for an unknown email address does not reveal whether that account exists.

There are also account lifecycle notifications for events such as:

successful email verification
password changes
password resets
account deletion

The EmailSender interface decides how those messages are delivered, but it does not decide when the operation is valid. That decision remains in the core.

SQLAlchemy without owning your application

The official SQLAlchemy adapter is useful out of the box, but one design requirement was that adopting UserHarbor should not force an application to adopt a completely separate user model.

By default, the adapter can manage its own user table.

But applications that already have a SQLAlchemy model can provide it instead:

store = SQLAlchemyUserStore(
    SessionLocal,
    user_model=AppUser,
)

Applications can also map their model to a richer public user object instead of being limited to UserHarbor's minimal representation.

The documentation now also covers using the adapter with Alembic migrations rather than relying on metadata.create_all() at application startup.

That distinction matters because examples should be easy to run, but real applications need a sensible path toward managing schema changes properly.

Installation

The core can be installed on its own:

pip install userharbor

Or with selected official integrations:

pip install "userharbor[sqlalchemy,smtp,fastapi]"

For experimenting with the complete official stack:

pip install "userharbor[all]"

The main official integrations currently include SQLAlchemy storage, SMTP email delivery and FastAPI support.

What I deliberately do not want UserHarbor to become

Feature creep is an easy trap for this kind of project.

Once you have authentication, it is tempting to add OAuth. Then social login. Then MFA. Organizations. Teams. ACLs. Resource ownership. Admin panels. A policy language.

Eventually the "small authentication library" becomes an application framework.

That is specifically what I am trying to avoid.

The core should remain focused on common account-management primitives.

More specialized functionality can exist as integrations or separate libraries if there is demand for it, but it should not make the basic package more complicated for everyone else.

One of the design principles of UserHarbor is therefore deliberately boring:

stability is more important than feature count.

Once the public API stabilizes, I would rather spend development effort on security, reliability, compatibility and performance than continuously expand the scope of the core.

Current status

UserHarbor is currently at version 0.7.0.

The project is still young, and I do not consider the API stable or the library ready for production use yet.

At this stage, the project is as much about validating the architecture as adding functionality.

The areas I am particularly interested in getting feedback on are:

the boundary between the core and integrations
the UserStore contract
the contract-testing approach
the FastAPI integration
custom storage backends
the shape of the public API
what should — and should not — belong in the core

There are plenty of good framework-specific authentication libraries in Python.

UserHarbor is exploring a slightly different question:

Can the account-management domain itself be reusable across frameworks and infrastructure, while integrations remain small, replaceable and independently testable?

So far, I think that boundary is turning out to be the most interesting part of the project.

Links

Documentation:
https://userharbor.github.io

Repository:
https://github.com/userharbor/userharbor

FastAPI integration:
https://github.com/userharbor/userharbor-fastapi

SQLAlchemy adapter:
https://github.com/userharbor/userharbor-sqlalchemy

SMTP adapter:
https://github.com/userharbor/userharbor-smtp

Looking for contributors to help debug an AI-powered Network Traffic Analyzer (FastAPI + Scapy)

Fri, 17 Jul 2026 12:35:07 +0000

Hi everyone,

I've been building NetGuard, an open-source AI-powered Network Traffic Analyzer and Active Defense Platform built with FastAPI, Scapy, SQLite, and a Random Forest model trained on the NSL-KDD dataset.

The project currently includes:

Live packet capture
Rule-based IDS
Traffic visualization dashboard
AI traffic classification
Automatic IP blocking using iptables
Threat remediation recommendations

Most of the architecture is working, but I'm currently stuck on a few integration issues.

The biggest one:

The orchestrator successfully receives HTTP 200 OK from the classifier, but ai_result is always null. I suspect a payload mismatch or response parsing issue inside call_classifier().

There are also a couple of other issues involving SQLite alert persistence and PDF report generation.

I've documented everything in the README, including reproduction steps and setup instructions.

GitHub:
https://github.com/GulrezQayyum/netguard

If anyone enjoys debugging FastAPI, async Python, networking, or ML integrations, I'd really appreciate your feedback or pull requests.

Thanks!

I Build a blog API with Redis - Here's every problem I Hit

Wed, 15 Jul 2026 00:51:31 +0000

I build a blog API with FastAPI + Redis + MySQL.
Three cache problems almost killed my app.
If you also face these problems!
Here's how I fixed each one.

1. Cache Penetration

What's Cache Penetration?

Cache Penetration refers to a scenario where the requested data exists neither in cache nor in the database,causing every request to hit the database directly,thereby increasing the database load.

How to solve?

1.Caching null values

Steps:

When a queried key exists in neither the cache nor the database,the result (such as null or an empty value) is cached with a short TTL.
This way,subsequent identical requests can be served directly from the cache,avoiding frequent database access.

Example:

...
redis = get_redis()
data = redis.get(cache_key)

# First, check the cache. If the cache entry exists, check whether it is __NULL__
if data is not None:
    if data == "__NULL__":
        return {"data": None, "source": "cache"}
    return {"data": data, "source": "cache"}

# Second, cache miss, query database
value = query_database(cache_key)

# Third, cache the result whether it exists in DB or not
if value is not None:
    redis.setex(cache_key, 60, value)          # cache real data
else:
    redis.setex(cache_key, 10, "__NULL__")     # cache null sentinel (short TTL)

return value

2.Cache breakdown

What's Cache breakdown?

Cache breakdownoccurs when a popular data entry expires in the cache while a massive number of concurrent requests are hitting that same data at the exact same time.All those requests penetrate straight through to the database,putting enormous pressure on it and potentially causing system performance issues.

How to solve?

Lock mechanism:When the cache expires,use a locking mechanism to ensure that only one thread can access the database and update the cache.The other threads wait util the cache is rebuilt before reading the data.

Example:

# Generate a lock key based on the given key
lock_key = f"mutex:{key}"

# Use SETNX operation to acquire the lock. If the key does not exist, set it with an expiration time of 300 seconds.
# This prevents concurrent access.
lock_acquired = redis_client.set(lock_key, "1", nx=True, ex=300)

if lock_acquired:
    try:
        # Successfully acquired the lock, query the database
        value = db_query_func(key)
        if value is not None:
            # Write the result to the cache with an expiration time of 3600 seconds
            redis_client.setex(key, 3600, value)
        return value
    finally:
        # Release the lock
        redis_client.delete(lock_key)
else:
    # Failed to acquire the lock, sleep for 0.1 seconds and then retry
    time.sleep(0.1)
    return get_data_with_mutex(key, redis_client, db_query_func)

3.Cache avalanche

What's cache avalanche?

Cache avalancerefers to a situation where a large amount of cached data expires at the same time or the cache service goes down. As a result, all requests are directly sent to the database, causing a sudden surge in the database's pressure and even leading to its downtime.

How to solve?

Randomized TTL

The core idea is to avoid a large number of keys expiring simultaneously.
When setting the expiration time for the cache, add a random value.

Example:

import random

expire_time = time + random.randint(0,300)
redis.set(key,value,ex=expire_time)

What about you?

Have you run into any of these cache problems in your projects?
Or do you use a different strategy? Let me know in the comments

If this was helpful, follow me for more backend deep dives.

Hardening Two Multi Tenant SaaS APIs:

Fri, 05 Jun 2026 18:24:16 +0000

Hardening Two Multi Tenant SaaS APIs

What We Found, What We Fixed, and What Changed

Security hardening is not glamorous work.

Most of it is careful reading, careful verification, uncomfortable edge cases, and refusing to trust assumptions that have quietly become part of the system.

Recently, I completed a remediation pass across two multi tenant SaaS products: Site2CRM and Made4Founders. Both products had grown into real platforms with authenticated dashboards, public webhooks, billing flows, CRM integrations, OAuth style connections, file uploads, background jobs, and customer owned data.

That kind of product has a wide attack surface.

The work started with security reports and ended with two hardened branches, 24 total commits, more than 140 new regression tests, database migrations, centralized security utilities, audit logging, startup gates, and CI checks that now block the same classes of mistakes from coming back.

This article is a breakdown of what we found, how we fixed it, and the engineering lessons that came out of the process.

The Goal Was Not Just to Close Findings

A security report usually arrives as a list of issues.

That can make the work feel transactional.

Fix this endpoint.

Add this check.

Reject this payload.

Patch this route.

That is necessary, but it is not enough.

The real question is:

What class of mistake allowed this bug to exist?

That question changed the remediation strategy.

For every finding, the goal became clear:

Fix the specific issue.
Add a regression test for that finding.
Centralize the security pattern where possible.
Add a guard so the same mistake is harder to reintroduce.
Document any deployment or data migration steps clearly.

That approach turned the work from a cleanup pass into a hardening pass.

Finding 1: Tenant Data Must Always Be Scoped by Tenant

In a multi tenant application, the most important security rule is simple:

A customer should only be able to access data that belongs to their organization.

That rule sounds obvious, but enforcing it consistently is where systems get tested.

A risky query often looks harmless:

lead = db.query(Lead).filter(Lead.id == lead_id).first()

The problem is that lead_id alone is not a tenant boundary.

In a multi tenant system, the query needs to prove both identity and ownership:

lead = (
    db.query(Lead)
    .filter(
        Lead.id == lead_id,
        Lead.organization_id == current_user.organization_id,
    )
    .first()
)

The same principle applies to updates, deletes, dashboard feeds, background jobs, calendar items, configuration records, and integration data.

In one case, a calendar feed was using a join path that could leak data across tenants. In another, a vault configuration model had rows that were not safely attached to an organization. Both issues were fixed by making organization ownership explicit, adding migrations where needed, and creating regression coverage around the exact failure modes.

The broader lesson was this:

Tenant isolation should not depend on developer memory.

It should be a pattern the codebase makes easy and the test suite actively defends.

Finding 2: Organization Admins Are Not Platform Admins

One of the clearest authorization lessons came from a global resource protected by a tenant level role check.

Most SaaS products have organization roles like:

OWNER
ADMIN
USER

Those roles are useful inside a customer account. An organization owner should be able to manage users, settings, forms, integrations, and billing details for that organization.

But tenant authority is not platform authority.

A customer OWNER should not be able to manage global platform resources, issue marketplace codes, access internal tools, or make changes that affect other organizations.

The risky pattern was conceptually simple:

if current_user.role not in ["OWNER", "ADMIN"]:
    raise HTTPException(status_code=403)

That check answers the wrong question.

It asks:

Is this user powerful inside their own organization?

For global platform actions, the application needs to ask a different question:

Is this user actually trusted to operate the platform itself?

The fix was to introduce a real platform staff boundary and move global operations behind that boundary:

require_platform_staff(current_user)

This was not just a one line fix. Tests were added to prove that tenant owners and tenant admins could not access platform scoped functionality. A static guard was also added so future global table routes cannot quietly be protected only by tenant roles.

The lesson:

Never reuse customer roles for platform administration.

They represent different trust models.

Finding 3: Public Webhooks Are Public, Not Trusted

Public webhook endpoints need to be reachable by external providers.

That does not mean they should trust incoming requests.

Several webhook surfaces needed stronger sender verification. The risk was not that the endpoints existed. The risk was that state changing payloads could be processed without proving they came from the provider they claimed to represent.

The corrected model is straightforward:

Read the raw request body.
Verify the provider signature.
Reject missing or invalid signatures.
Parse the payload only after verification.
Apply idempotency where relevant.
Mutate state.
Return success.

This mattered for provider events such as inbound messaging events, email bounce and complaint notifications, and billing lifecycle events.

Billing webhooks received extra attention because they can change plan state. A forged billing event can potentially activate, cancel, downgrade, or otherwise alter customer access.

The fix was to make verification mandatory. If the provider webhook secret or webhook ID is missing in production, the app should fail closed. If the signature is invalid, the route should reject the request instead of logging the error and continuing.

The lesson:

A webhook endpoint can be public without being trusted.

Reachability and trust are separate things.

Finding 4: External Install Identifiers Are Not Authentication

One integration trusted a client supplied install identifier as if it were a credential.

That is dangerous.

Install IDs, instance IDs, account IDs, and external resource IDs are identifiers. They are not proof that the caller owns the installation.

The hardened approach was to require a signed provider token, verify it server side, and only then extract the canonical installation identity from the verified payload.

The corrected flow became clear:

Receive signed provider instance token.
Verify the token using the provider app secret.
Extract the canonical instance ID from the verified payload.
Resolve the install record from that verified identity.
Refuse cross organization rebinding unless ownership is proven.

This fixed both the authentication issue and the related install rebinding risk.

The lesson:

Do not authenticate integrations with bare IDs.

Use provider signed assertions, server side verification, and explicit ownership rules.

Finding 5: User Controlled URLs Need SSRF Protection

Several features across the two products involved server side requests to external URLs.

That pattern is common:

Outbound webhooks
RSS imports
Social integrations
Callback URLs
Remote media fetches
Health checks

The security risk is SSRF, or Server Side Request Forgery.

SSRF occurs when a user can influence a URL that the server requests. Without guardrails, an attacker may be able to point the server at internal infrastructure.

Examples include localhost, private network addresses, cloud metadata services, link local addresses, and internal admin panels.

The fix was to centralize outbound fetching through a safe fetch utility.

That utility blocks dangerous destinations, applies timeouts, restricts redirects, limits response size, and prevents internal response bodies from being reflected back to users.

The important part was centralization.

Instead of asking every route to remember SSRF rules, risky outbound requests now go through one safer path.

The lesson:

Any feature that lets a user provide a URL should be treated as a network boundary.

Finding 6: Cryptography Should Not Have Production Fallbacks

Development conveniences can become production vulnerabilities if they are allowed to survive past local use.

The hardening pass removed weak secret fallbacks and hardcoded encryption key fallbacks. Token encryption was versioned, and a re encryption path was added so legacy stored values could be migrated safely.

The improved model included several important rules:

No hardcoded production fallback keys.
An explicit application encryption key requirement.
A versioned encrypted token format.
A migration script for legacy tokens.
A production flag to reject legacy plaintext tokens after migration.

The lesson:

Cryptographic failure should be loud.

If the key is missing in production, the app should not quietly invent one.

Finding 7: File Uploads Should Stay Boring

File uploads are easy to underestimate.

For brand logos and media uploads, the safest approach was to restrict formats and improve storage behavior.

The hardening changes included rejecting risky file types where they were unnecessary, using high entropy media names, enforcing body size limits, handling chunked uploads safely, and avoiding active content in logo uploads.

One practical example was SVG.

SVG can be useful, but it can also contain active content. If served from the wrong origin or with weak headers, it can become a stored XSS risk.

XSS means Cross Site Scripting. It occurs when attacker controlled content executes JavaScript in a trusted browser context.

For a logo upload feature, SVG was not worth the additional risk.

The lesson:

If a product only needs images, do not accept formats that behave like documents or code.

Finding 8: Security Relevant Configuration Should Fail Closed

Some risks were not about code paths. They were about missing configuration.

Examples included missing webhook secrets, missing encryption keys, missing CAPTCHA secrets, missing Redis for rate limiting, weak application secret keys, and insecure production cookie settings.

The fix was to add production startup gates.

In development, flexible configuration is helpful.

In production, missing security configuration should stop the app from starting.

A startup gate turns a hidden runtime weakness into an obvious deployment failure.

The lesson:

Failing to boot is better than booting insecurely.

Finding 9: Rate Limiting Should Not Silently Degrade

Rate limiting is often treated as a nice to have, but for authentication and abuse prevention it is a security control.

If Redis is unavailable and the system silently falls back to per process memory, limits become weaker under multiple workers.

For example, a limit of 10 attempts may effectively become 40 attempts across four workers.

The production behavior was hardened so that security sensitive rate limiting depends on a real shared backend.

The lesson:

A degraded security control should be visible, not silent.

Finding 10: Regression Tests Are Part of the Fix

Every meaningful finding received a named regression test.

That mattered.

A test named after a security issue tells future maintainers why the behavior exists. It also prevents a fix from being accidentally removed during a refactor.

Examples of the test coverage included:

Tenant data cannot be accessed across organizations.
Platform scoped routes require platform staff.
Unsigned webhooks are rejected.
Invalid webhook signatures are rejected.
Unsafe webhook URLs are rejected.
SVG logo uploads are rejected.
Weak production secrets fail startup.
Legacy plaintext tokens can be rejected after migration.

The lesson:

If a security issue was important enough to fix, it is important enough to test.

Finding 11: Static Guards Catch What Tests Miss

Tests are excellent for specific behavior.

Static lint is better for broad architectural patterns.

Both repositories now have security lint guards for risky patterns:

Tenant owned queries without organization scope.
Raw outbound requests using user controlled URLs.
State changing public routes without auth or signature classification.
Global platform routes protected only by tenant roles.

The linter supports a baseline, which is important for mature codebases.

A baseline allows known accepted cases to remain documented while CI fails only on new violations. That keeps the guard practical instead of noisy.

The preferred workflow is simple:

Fix the violation.
Add a clearly marked exception only when intentional.
Update the baseline only when the exception is reviewed and accepted.

The lesson:

The best time to add a guard is right after fixing the bug class.

That is when the pattern is fresh, the risk is understood, and the team knows what should never happen again.

Finding 12: Some Fixes Require Operational Discipline

Not every security fix ends with a commit.

Some work has to happen during deployment.

Examples include coordinating breaking integration changes, setting required production secrets, running database migrations, inspecting quarantined records, re encrypting stored tokens, enabling flags that reject legacy formats, scrubbing sensitive files from Git history, and running full test suites before release.

These steps were intentionally left as human controlled actions because they affect production data, integration behavior, and deployment timing.

That is part of responsible hardening.

The code can be ready before production is ready.

The lesson:

A remediation branch is not deployable until the operational checklist is complete.

What Changed by the End

Across both products, the hardening pass produced:

24 total commits.
More than 140 new regression tests.
Database migrations.
Centralized webhook verification.
Centralized SSRF safe fetch behavior.
Fail closed production startup gates.
Platform staff authorization.
Audit logging for sensitive actions.
Versioned token encryption.
Tenant isolation checks.
Security lint guards enforced in CI.
Main branches left untouched for review.

More importantly, the products now have better security shape.

The fixes were not just scattered patches. They became reusable boundaries.

Tenant data access now has stronger conventions.

Platform operations now have a separate trust model.

Webhook verification now follows a consistent pattern.

Outbound URL fetching now has a safer path.

Production misconfiguration now fails early.

Dangerous patterns now have CI visibility.

Final Takeaway

The most valuable security work is not only fixing what was found.

It is asking what the finding reveals about the system.

A good remediation process should answer several questions:

What failed?
Where else could it fail?
What is the correct shared pattern?
How do we test the fix?
How do we prevent the class from returning?
What must be true before deployment?

That mindset turns a security report into a stronger codebase.

Patching closes issues.

Hardening changes the system.

Building an AI Product Backend From Scratch: FastAPI, Postgres, pgvector, Stripe, and What I'd Do Di

Mon, 18 May 2026 02:16:31 +0000

A couple of years ago I was hired as the solo backend engineer to build the production backend for an AI product company from scratch. No legacy code, no existing schema, no team to defer to — just a frontend team waiting on an API and a product team waiting on inference. This post is about the architecture decisions I made, what worked, and what I'd do differently if I were starting today.
The shape of the problem
The product needed five things working together:

A typed API for the frontend
LLM inference with reasonable UX (streaming, cost controls, retries)
Vector search over user-supplied content
Authentication and user management
Subscription billing

Standard stuff individually. The interesting part was keeping the operational footprint small enough that one person could run the whole thing without it falling over.
Why FastAPI + Postgres + pgvector
The temptation when building an AI product is to reach for a Lambda-and-microservices architecture from day one. I went the other direction: one FastAPI service, one Postgres database, pgvector for embeddings inside that same Postgres.
The reasoning:

One database, one source of truth. User data, subscription state, and vector embeddings live in the same Postgres. No sync issues between Postgres and a separate vector DB. Backups are one operation. Migrations are one tool (Alembic).
FastAPI's typing pays for itself. Pydantic schemas become the contract with the frontend. OpenAPI generation is free. Async support means LLM calls and external APIs don't block the event loop.
One service is faster to ship and easier to debug. When something breaks at 2am, you don't have to figure out which of seven services owns the bug.

The cost: at very high scale (millions of users, billions of embeddings), pgvector and a monolithic FastAPI service would need rethinking. For an early-stage product, this was the right tradeoff.
LLM integration: the part people underestimate
Connecting to an LLM API is one line of code. Making it production-grade is most of the engineering work. The pieces:

Streaming responses. Users will not wait 15 seconds for a wall of text. Server-sent events from FastAPI through to the frontend, with proper backpressure handling.
Token accounting per user. Every request logs prompt tokens, completion tokens, and cost. Without this you have no idea who's burning your budget.
Soft caps + fallback models. Hitting a per-user daily limit doesn't return an error — it switches to a cheaper model and continues. Users get a worse experience, not a broken one.
Retry with backoff that respects rate limits. Upstream providers throttle. Naive retry loops make it worse. Exponential backoff plus reading the Retry-After header is the minimum.
Prompt templates separated from application code. Templates live in their own module, versioned, with the application code only choosing which one to invoke. Changes to wording don't require touching business logic.

Vector search inside Postgres
pgvector is one of the more underrated decisions you can make. It's a Postgres extension that adds a vector type and similarity-search operators. You get nearest-neighbor queries with the same SQL you use for everything else, the same transaction guarantees, and the same backup story.
The gotchas worth knowing:

Indexes matter a lot. A naive sequential scan over a few hundred thousand vectors will be slow. IVFFlat or HNSW indexes are not optional past a certain table size.
Chunking is where retrieval quality lives. Embedding a 50-page document as one vector is useless. Chunk strategy (size, overlap, semantic boundaries) affects results more than the embedding model choice.
Re-embedding is expensive. When you change embedding models or chunking strategy, you re-embed everything. Design the ingestion pipeline so this isn't catastrophic.

Subscription billing: webhooks are the product
Stripe handles the payment UI and the regulatory complexity. Your job is to receive its webhooks and turn them into entitlements in your database.
The non-negotiables:

Webhooks must be idempotent. Stripe will deliver the same event twice. If your subscription state changes twice, you've granted access twice or revoked it incorrectly.
Webhook signature verification on every request. Without it, anyone can POST a fake "subscription.created" event to your endpoint.
Entitlements as a separate layer. Don't check Stripe's subscription status in every API handler. Maintain a local entitlements table updated by webhooks; check that. It's faster, more reliable, and survives Stripe outages.
Reconciliation jobs. Webhooks fail. A nightly job that pulls the truth from Stripe and reconciles your local state catches the gaps before users notice.

Auth: boring is correct
Email/password with hashed credentials, OAuth for social sign-in, JWT for sessions with refresh tokens, role-based access control on routes. None of this is novel and none of it should be. The mistake people make on AI products is wanting auth to be clever. It shouldn't be. Pick well-tested libraries and move on.
What I'd do differently today
A few things have changed in the 2-3 years since:

Structured outputs. Most LLM providers now support enforced JSON schema responses. When I built this, you parsed JSON out of completions and prayed. Today I'd use structured outputs everywhere they're supported and delete a lot of validation code.
Streaming standards. The streaming UX patterns are much more mature now. Vercel AI SDK and similar libraries handle a lot of what I wrote by hand.
Embedding model choices. The embedding landscape moved fast. I'd benchmark a few current options against the actual retrieval task instead of defaulting to OpenAI embeddings.
Observability from day one. I added logging and error reporting, but I'd build proper LLM-aware observability (token usage, latency percentiles, prompt versions, retrieval quality) into the request path from the first commit.

Takeaways
If you're building an AI product backend:

One service and one database will take you further than you think
Most of the engineering work is around the LLM call, not the LLM call itself
pgvector is a serious option if you're already on Postgres
Webhook idempotency and entitlement layers will save you from a class of bugs that are hard to debug after the fact

Happy to dig into any of these in the comments — especially if you've made different architectural choices and have war stories to share.

The Executive Interface: Translating AI Telemetry into C-Level Decisions

Sun, 17 May 2026 07:27:53 +0000

The most highly engineered artificial intelligence backend fails to secure financial viability if upper management lacks the mechanism to visualize its direct impact on profitability. Applied Operations Engineering does not terminate inherently within a relational database architecture; the structural cycle invariably concludes on the decision-maker’s screen.

The asynchronous orchestration model implemented in previous segments (CrewAI piloting an LLM securely against deterministic SQL Supabase arrays) yields robust operational execution. This concluding segment reinforces the deployment by exposing the mathematical core toward a managerial interface deliberately calibrated exclusively to communicate Return on Investment (ROI) calculations and industrial downtime mitigation.

The Standardized Data Contract: Formulating the Analytical API

In order to rigorously decouple the cognitive analysis load originating from the underlying agent engines, balancing execution layers evenly across the network, we introduce a simulated Read-Replica structure atop the FastAPI environment (dashboard_api.py).

This REST terminal strictly exposes mathematical telemetry archived implicitly by our evaluating Agent resolving inbound PDNs:

@app.get("/api/v1/dashboard/risk-metrics")
def get_risk_metrics():
    # Enforces a static JSON contract for Frontend ingestion
    return {
        "total_risk_eur": 15450.00,
        "active_alerts": 2,
        "affected_skus": [
            {
                "sku": "DRONE-X1",
                "margin_at_risk": 12500.00,
                "status": "CRITICAL LTB REQUIRED",
                "trigger_mpn": "TI-CAP-10U-50"
            }
            # ...
        ],
        "agent_logs": [
            "[18:31:02] [Webhook] Inbound email parsed.",
            "[18:31:05] [CrewAI] Parsing semantic text. MPN extracted: TI-CAP-10U-50.",
            "[18:31:07] [CrewAI] P&L calculated. Retained Margin at Risk: 12,500.00 EUR."
        ]
    }

The absolute numerical aggregate indexed directly as total_risk_eur unifies the financial exposure stemming from synchronous alert computations, guaranteeing clear C-Level synthesis.

The Frontend Engineering Paradigm: Minimalist Fundamentals

The modern software landscape predominantly cultivates vast dependencies enveloping Node.js-based heavy frameworks (such as React or Angular), frequently extending these burdens even toward purely unidirectional Read-Only telemetry boards.

Contrasting this convention, a functional operational factory monitor (Andon boarding mechanics) strictly dictates absolute instantaneous availability, zero massive transient module repositories, and static instantaneous rendering boundaries. Employing rigid Dogfooding and adherence to strict First Principles methodologies, we outline a standard static index.html directly provisioned via CDN utilities.

The underlying stack distills precisely toward standard native Web API functionalities mapping the unadorned Fetch() standard enclosed inside strict Vanilla JavaScript bound dynamically by atomic atomic styling via Tailwind CSS.

fetch("http://localhost:8001/api/v1/dashboard/risk-metrics")
    .then(response => response.json())
    .then(data => {
        // Enforcing Macro-Econometric bindings
        document.getElementById('totalRisk').innerText =
            new Intl.NumberFormat('en-US', { style: 'currency', currency: 'EUR' }).format(data.total_risk_eur);
       
        // Channeling active event telemetry loops
        const consoleDiv = document.getElementById('telemetryConsole');
        data.agent_logs.forEach(log => {
            const line = document.createElement('div');
            line.innerText = `> ${log}`;
            consoleDiv.appendChild(line);
        });
    });

Visual Engineering for Critical Operations: Industrial UX

To aggressively preempt “Analysis Paralysis” constraints across executive viewers, structural interface segregation clusters data exclusively within three core categorical axes:

The Critical Analysis Threshold (Macro KPI): Disclosing the consolidated risk metric bound heavily inside an unmissable perimeter. Direct and literal exposure communicating the 15,450.00 EUR justifying the technological expenditure securing AI frameworks within the board room.
Constraint Tabulation (Blacklist Registers): A starkly structured matrix elevating purely the top-tier commercial product identifier base (DRONE-X1), deliberately isolating the complex inner web of microscopic resistors below. The target centers entirely upon final operational line constraints.
The Live Core (Active Telemetry Processing): Real-time monitoring console mapped visually to broadcast the raw cognitive iterations driven by the internal CrewAI process. Reassuring operational directors visually confirming the endless, uninterrupted analytic progression actively shielding logistics lines without manual prompting.

Series Culmination: A Blue Ocean Extracted in Logistics

This specific deployment sequence concludes our intensive technical trajectory mapped consistently to operational engineering, advancing drastically past speculative archaic forecasting techniques relying broadly on weak statistical projections.

We acknowledged material component obsolescence strictly as systematic margin erosion outlined prominently across IEC 62402 requirements. We encoded intricate supply interdependencies mapping vectors within rigorous recursive Graph databases. We algorithmically neutralized chaotic raw ingestion inconsistencies integrating Pandas filters; allocated heavily restrained advanced Language Agents dynamically converting abstract linguistic payloads autonomously into structured data matrices, and decisively scaled robust event-driven operations persistently spanning active Background FastAPI nodes.

Physical logistics obsolescence fundamentally resigns its classification as an uncontrollable, unpredictable Black Swan occurrence. Converted exclusively into a precisely measurable, purely mitigated domestic phenomenon, we have ultimately established a definitive and asymmetric tactical advantage securing systemic industrial resilience.

The Central Nervous System: Scaling the Agentic Radar to 24/7 with FastAPI and Webhooks

Sat, 09 May 2026 08:48:42 +0000

In the previous section of this series, we demonstrated that Artificial Intelligence can calculate the P&L impact of component obsolescence. This was achieved by isolating the semantic inference module from execution, using deterministic SQL tools.

However, running a Python script locally in a terminal is not suitable for production. Product Discontinuance Notices (PDNs) arrive continuously across global time zones. Supply chain operations require a centralized, continuous, and scalable system.

To achieve production readiness, the architecture must transition to an Event-Driven Architecture (EDA).

Blueprint Topology: Legacy Vectors vs. Modern API Frameworks

At the architectural level, supply chain logistics systems must accommodate two distinct alert ingestion methods:

The Modern API Vector (B2B SaaS): Commercial component lifecycle management tools, such as SiliconExpert or Accuris, provide structured data. These platforms dispatch standardized JSON payloads detailing market lifecycle transitions.
The Legacy Vector (Email): Many manufacturers and Tier 2 suppliers continue to use plain text emails or PDF attachments to announce fabrication facility shutdowns or EOL statuses.

The Software Engineering Decision: Polling IMAP mailboxes continuously with Python processes is resource-intensive and prone to latency. Instead, we use Inbound Parse gateways (like SendGrid or Mailgun). These services intercept emails, extract the relevant properties (Subject, Body), package them into a standardized JSON payload, and forward them to an integration endpoint. Through this approach, both communication channels are normalized into standard HTTPS POST requests.

Routing Logic: Structuring the Backbone with FastAPI

We utilize FastAPI to build the asynchronous microservice in Python. The objective is to deploy a routing layer that directs incoming alerts to the CrewAI framework.

The following simplified code demonstrates the dual webhook implementation:

@app.post("/api/v1/webhooks/commercial-radar")
async def commercial_radar_webhook(alert: CommercialAlert, background_tasks: BackgroundTasks):
    # Vector 1 Protocol: Commercial API Consumption
    synthetic_pdn = f"Manufacturer: {alert.manufacturer}. MPN: {alert.mpn}. Status: EOL."
    
    background_tasks.add_task(process_obsolescence_background, synthetic_pdn)
    return {"status": "accepted"}

@app.post("/api/v1/webhooks/inbound-email")
async def inbound_email_webhook(email: InboundEmail, background_tasks: BackgroundTasks):
    # Vector 2 Protocol: Inbound Parsed Email Payload
    pdn_text = f"Subject: {email.subject}\nBody: {email.text}"
    
    background_tasks.add_task(process_obsolescence_background, pdn_text)
    return {"status": "accepted"}

Asynchronous Execution: Handling LLM Latency

The snippet above highlights a mandatory pattern for web resilience when integrating LLMs. A CrewAI-orchestrated inference cycle typically requires 5 to 15 seconds to complete. This process involves parsing the input, extracting the part number, querying the Supabase relational graph, calculating the financial impact, and formatting the response.

Keeping the HTTP socket open while awaiting this execution will cause the sending API (e.g., SendGrid) to encounter a Timeout error (usually capped at 10 seconds), leading to redundant internal retries. The standard solution is to decouple the execution using Background Tasks.

The server immediately returns an "HTTP 202 Accepted" status code, closing the connection with the client. Concurrently, the internal worker instantiates the LLM operations in the background without blocking network resources.

The Closed Control Loop: System Notifications

If the autonomous agent successfully evaluates the downtime risk but only logs the output locally, the system does not fulfill its operational purpose. The output data must be pushed to the relevant stakeholders.

The final stage of the architecture involves sending the generated mitigation brief to the procurement team's communication channels (such as Microsoft Teams or Slack) via an outbound webhook.

def process_obsolescence_background(pdn_text: str):
    # ... Multi-Agent Inference Iteration ...
    assessment = execute_obsolescence_analysis(pdn_text)
    
    # MS Teams/Slack Procurement Alert
    header = f" Agentic P&L Alert Processed\n"
    notify_teams(header + str(assessment))

Complete System Architecture

The integration of these modules forms an event-driven pipeline where SQL table queries and LLM text processing operate together asynchronously.

Next Steps

We have configured the data ingestion engine (Block 2), established the semantic inference framework (Block 3), and deployed an API-centric service to process global component anomalies 24/7 (Block 4).

In the final segment of this engineering series, we will focus on data visualization. We will document how to expose these asynchronous alerts by building an Executive Dashboard, making the agent's operations accessible for management review.

Getting Started with Google Colab: Run Python in the Cloud for Free

Sat, 21 Mar 2026 09:05:41 +0000

If you want to write and run Python code without installing anything on your machine, Google Colab is one of the easiest ways to start.

Whether you're learning Python, building AI models, or analyzing data, Colab gives you a powerful environment—right in your browser.

What is Google Colab?

Google Colab (short for Colaboratory) is a cloud-based notebook environment that lets you:

Write and execute Python code
Use GPUs/TPUs for free
Share notebooks like Google Docs
Install libraries on the fly

Think of it as:

Jupyter Notebook + Free Cloud Compute + Collaboration

⚡ Why Developers Love Colab

No setup required – runs in your browser
Free GPU access – great for AI/ML
Auto-saves to Google Drive
Easy sharing & collaboration
Pre-installed libraries (NumPy, Pandas, TensorFlow, PyTorch)

️ Getting Started Step-by-Step

Step 1: Open Google Colab

Go to Colab
Sign in with your Google account

Step 2: Create a New Notebook

Click “New Notebook”
A .ipynb file opens instantly

Step 3: Understand the Interface

Code cells → write Python code
Text cells → write notes (Markdown)
Run button ▶️ → execute code

✍️ Your First Code

Example: Hello World

print("Hello, Google Colab!")

Click ▶️ and see output instantly.

Example: Data Analysis

import pandas as pd

data = {
    "Name": ["Alice", "Bob", "Charlie"],
    "Score": [85, 90, 95]
}

df = pd.DataFrame(data)
df

Output is displayed as a clean table.

Using Colab for AI/ML

Colab is widely used for:

Training machine learning models
Running deep learning experiments
Building NLP applications
Prototyping AI ideas

Enable GPU

Click Runtime → Change runtime type
Select GPU

Now your notebook runs faster for heavy tasks.

Installing Libraries

Need extra packages? Just run:

!pip install transformers

Working with Files

Upload file

from google.colab import files
files.upload()

Mount Google Drive

from google.colab import drive
drive.mount('/content/drive')

Click Share
Add collaborators
Set permissions (view/edit)

Just like Google Docs!

Real-World Use Cases

Data analysis & visualization
Machine learning experiments
AI model prototyping
Teaching & tutorials
Research projects

⚠️ Limitations to Know

Sessions disconnect after inactivity
Limited compute time
Not ideal for production apps

When Should You Use Colab?

Use it when you want to:

Learn Python or ML
Prototype quickly
Avoid local setup
Use GPU without cost

Avoid it when:

Building production systems
Running long-duration jobs

Final Thoughts

Google Colab removes the friction of setup and gives you instant access to powerful computing.

Instead of worrying about environments, you can focus on:

Learning, experimenting, and building

What to Try Next

Train a simple ML model
Use Hugging Face transformers
Build a chatbot
Analyze a dataset
Visualize data with Matplotlib

kind of free GPU
https://colab.research.google.com/

Dashboard Operasional Armada Rental Mobil dengan Python + FastAPI

Thu, 12 Mar 2026 17:00:00 +0000

Di banyak bisnis rental, masalahnya bukan kekurangan data—melainkan data tercecer: ketersediaan unit ada di chat, jadwal servis ada di catatan, dan laporan pemakaian tercebur di spreadsheet. Tren “dashboard-first” yang sering dibahas komunitas (misalnya artikel CoderLegion tentang dashboard monitoring Python + FastAPI) membuat kita bisa merapikan alur operasional jadi satu layar. Di artikel ini, kita bongkar cara membangun dashboard operasional armada rental yang ringan, real-time, dan enak dipakai tim lapangan.

Secara akademik, pendekatan dashboard monitoring terbukti membantu efisiensi pemantauan dan akurasi pelaporan pada studi pengembangan dashboard monitoring proyek (lihat landasan pada jurnal dashboard monitoring berbasis KPI). Walau konteksnya bukan rental mobil, prinsipnya identik: KPI yang terukur + visualisasi yang tepat = keputusan lebih cepat. Itu alasan kenapa tema ini relevan untuk pembaca developer: kalian bisa membawa “engineering mindset” ke problem operasional yang nyata.

“Dashboard yang bagus itu bukan sekadar cantik—dia memotong waktu debat, mempercepat keputusan, dan mengurangi miskomunikasi.”

1. Kenapa Dashboard Operasional Itu Penting untuk Armada Rental

Sebelum nulis satu baris kode, kita perlu sepakat: dashboard bukan “aksesori”, tapi control plane untuk operasional. Kalau operasional kamu masih bergantung pada ingatan admin dan scroll chat panjang, risiko bentrok jadwal, servis telat, dan salah alokasi unit itu tinggal menunggu waktu.

Masalah yang sering kejadian di lapangan

Double booking: unit dianggap available karena belum di-update.
Servis kelewat: jadwal maintenance tidak punya pengingat yang konsisten.
Laporan pemakaian bias: data odometer/BBM masuknya sporadis.
SLA respon lambat: customer nunggu kepastian unit karena admin cek manual.

KPI yang “wajib ada” untuk rental

Agar dashboard operasional armada rental tidak jadi pajangan, tetapkan KPI sederhana:

Utilization rate per tipe kendaraan
Availability harian (available / on-rent / maintenance)
On-time return rate
Jumlah unit “overdue service”
Lead time dari inquiry → konfirmasi

2. Data Model Minimal yang Bikin Dashboard Nendang

Dashboard yang efektif biasanya justru lahir dari skema data yang tidak ribet. Mulai dari model minimal, lalu berkembang.

Entity yang disarankan

Fleet

vehicle_id, plate_number, type (sedan/SUV/minivan/city car/pickup), status

Booking

booking_id, vehicle_id, start_at, end_at, customer_name, channel (WA/web), status

Maintenance

maintenance_id, vehicle_id, service_type, due_at / due_odometer, status

Usage Log

usage_id, vehicle_id, date, odometer, fuel, notes

Tabel ringkas status unit (agar semua orang 1 bahasa)

Status	Definisi	Dampak di Dashboard
available	Unit siap disewa	Bisa dibooking
on_rent	Sedang dipakai customer	Tampil sebagai terpakai
maintenance	Servis/repair	Disembunyikan dari listing booking
hold	Diblock sementara (mis. inspeksi)	Perlu approval sebelum release

Tip: status hold sering menyelamatkan ketika ada unit “abu-abu” (baru balik, belum dicek).

3. Arsitektur Cepat: FastAPI sebagai Backend, Dashboard sebagai Produk

Untuk komunitas CoderLegion, stack paling “masuk akal” adalah FastAPI + Postgres + frontend dashboard (bisa Next.js, atau minimal Jinja/HTMX kalau mau hemat).

Komponen yang saya pakai (pragmatis)

FastAPI: REST + WebSocket untuk update real-time
PostgreSQL: data transaksi booking/servis
Redis (opsional): cache availability dan event stream
Background jobs: scheduler reminder servis & overdue return

Kenapa FastAPI cocok

Typed (Pydantic) → validasi data operasional rapi
Async-ready → cocok untuk notifikasi dan stream
Ekosistem luas → gampang integrasi scheduler, websocket, auth

Sebagai referensi internal yang relevan, kamu juga bisa lihat fastapi-bgtasks-dashboard untuk ide “observability” background task di ekosistem FastAPI.

4. Cara Menghitung Ketersediaan Unit Tanpa Drama

Bagian paling krusial dari dashboard operasional armada rental adalah availability engine. Kita tidak mau “available” versi admin A berbeda dengan admin B.

Prinsip kalkulasi

Ambil semua unit yang bukan maintenance dan bukan hold.
Untuk rentang waktu yang dipilih, cek apakah ada booking berstatus confirmed/active yang overlap.
Jika overlap → on_rent, jika tidak → available.

Edge case yang sering dilupakan

Booking yang extend (end time berubah)
Unit yang swap karena kerusakan
Booking pending (belum dibayar DP) — putuskan apakah memblok unit atau tidak

Tabel contoh aturan overlap

Kondisi	Overlap?	Status
booking end < start filter	tidak	available
booking start > end filter	tidak	available
booking start <= end filter dan booking end >= start filter	ya	on_rent

5. Jadwal Servis: Dari “Ingat-ingat” Jadi Sistematis

Di rental mobil, maintenance itu bukan biaya—dia investasi. Dashboard harus membuat servis terlihat dan actionable.

Pola yang efektif

Due by date: servis berkala tiap X bulan
Due by odometer: servis tiap X km
Alert window: misalnya H-7 / 500 km sebelum due

Checklist servis yang bisa ditampilkan

Oli + filter
Rem & kampas
Ban & rotasi
AC & filter kabin
Pemeriksaan kelistrikan

Pro tip: tampilkan widget “unit yang overdue” di atas. Manusia cenderung mengerjakan yang paling terlihat.

6. Laporan Pemakaian: Biar Keputusan Tarif Nggak Pakai Perasaan

Kalau kamu punya log odometer dan pemakaian, kamu bisa:

Deteksi unit yang “boros” (indikasi masalah mesin/ban)
Rekomendasi rotasi armada
Hitung biaya per km untuk evaluasi tarif

Format laporan yang enak dibaca

Per unit per minggu: km tempuh, hari terpakai, downtime
Per tipe kendaraan: utilisasi, revenue proxy, complaint rate
Top 5 penyebab downtime: maintenance, hold, overdue return

Contoh ringkas tabel laporan mingguan

Plat	Hari terpakai	KM	Downtime (hari)	Catatan
B 1234 XX	5	410	1	Servis oli
B 9876 YY	3	220	2	Ban depan

7. UI/UX Dashboard yang “CoderLegion Banget”

Di 2026, dashboard itu bukan sekadar chart. Ini tentang workflow.

Pola UI yang terasa modern

Global filter: tanggal, cabang, tipe kendaraan
Quick actions: tombol “Block unit”, “Jadwalkan servis”, “Extend booking”
Activity feed: perubahan status unit (audit trail)
Real-time badge: indikator data terakhir update

Microcopy yang membantu operasional

Daripada “Maintenance”, gunakan:

“Sedang Servis (estimasi selesai: …)”
“Hold: menunggu inspeksi”

Dengan microcopy yang jelas, dashboard operasional armada rental jadi “bahasa bersama” antara admin, driver, dan owner.

8. Security & Reliability: Jangan Sampai Dashboard Jadi Titik Lemah

Dashboard operasional itu sensitif: ada data customer, jadwal, dan status aset.

Minimal baseline yang saya sarankan

Auth: JWT + refresh token / session cookie
RBAC: admin, supervisor, driver
Audit log: siapa ubah status unit kapan
Rate limiting untuk endpoint publik

Observability yang simple tapi berguna

Log structured (JSON)
Metrics (request latency, error rate)
Tracing untuk alur booking → notifikasi → update status

FAQ

Q: Saya sudah pakai spreadsheet, perlu dashboard?
A: Spreadsheet bagus untuk input, tapi lemah untuk real-time visibility dan kontrol status. Dashboard mengurangi “interpretasi” dan mempercepat eksekusi.

Q: Harus WebSocket?
A: Tidak wajib. Kamu bisa mulai polling tiap 10–30 detik. WebSocket jadi relevan saat tim kamu banyak dan perubahan status sering.

Q: Bagaimana menghindari double booking?
A: Pastikan ada transaction/locking di sisi database saat konfirmasi booking, dan availability dihitung dari data booking yang sama.

Q: Tool frontend yang paling cepat?
A: Untuk MVP: Next.js + Tailwind + chart library. Untuk super cepat: template admin + fetch REST.

Q: KPI apa yang paling berdampak?
A: Availability harian + overdue service + overdue return. Tiga ini biasanya langsung terasa efeknya.

HowTo

Tentukan KPI inti (availability, overdue service, overdue return).
Buat data model minimal (Fleet, Booking, Maintenance, Usage Log).
Bangun API FastAPI untuk list unit, availability, servis, laporan.
Buat dashboard dengan global filter + widget prioritas (overdue).
Tambahkan audit log, RBAC, dan notifikasi operasional.

Dari Data Jadi Insight yang Bisa Dipakai Tim

Sebagai penutup, ingat bahwa tujuan utama dashboard operasional armada rental bukan “biar kelihatan canggih”, melainkan mengurangi friksi kerja: lebih sedikit cek manual, lebih sedikit miskomunikasi, dan lebih cepat ambil keputusan.

Carly Fiorina—mantan CEO Hewlett-Packard yang dikenal vokal soal kepemimpinan berbasis teknologi—pernah mengatakan: “The goal is to turn data into information, and information into insight.” Artinya: tujuan kita adalah mengubah data menjadi informasi, dan informasi menjadi wawasan. Kamu bisa cek kutipan dan profilnya di Wikiquote Carly Fiorina. Dalam konteks dashboard, ini mengingatkan kita bahwa angka mentah tidak cukup; yang dibutuhkan tim operasional adalah konteks, prioritas, dan tindakan berikutnya.

Jika kamu mengelola rental mobil di Karawang–Bekasi dan ingin operasional lebih rapi dengan pemesanan cepat serta dukungan 24 jam, kamu bisa lihat profil layanan kami di Oto Track untuk gambaran proses bisnis yang bisa dijadikan studi kasus implementasi dashboard.

{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "Membangun dashboard operasional armada rental dengan Python dan FastAPI",
  "description": "Panduan ringkas untuk membangun dashboard operasional armada rental: ketersediaan unit, jadwal servis, dan laporan pemakaian.",
  "totalTime": "PT6H",
  "supply": [
    {"@type": "HowToSupply", "name": "Database (PostgreSQL)"},
    {"@type": "HowToSupply", "name": "Python 3.11+"},
    {"@type": "HowToSupply", "name": "FastAPI"}
  ],
  "tool": [
    {"@type": "HowToTool", "name": "VS Code"},
    {"@type": "HowToTool", "name": "Docker (opsional)"}
  ],
  "step": [
    {
      "@type": "HowToStep",
      "name": "Definisikan KPI inti",
      "text": "Pilih KPI yang paling berdampak: availability harian, overdue service, overdue return.",
      "url": "https://coderlegion.com/"
    },
    {
      "@type": "HowToStep",
      "name": "Buat data model minimal",
      "text": "Siapkan entity Fleet, Booking, Maintenance, dan Usage Log agar status unit konsisten.",
      "url": "https://coderlegion.com/12111/membangun-dashboard-monitoring-proyek-konstruksi-dengan-python-fastapi-progress-lapor?is_promoted=1"
    },
    {
      "@type": "HowToStep",
      "name": "Implementasi API FastAPI",
      "text": "Bangun endpoint untuk ketersediaan unit, jadwal servis, dan laporan pemakaian dengan validasi Pydantic.",
      "url": "https://coderlegion.com/groups/PythonDev"
    },
    {
      "@type": "HowToStep",
      "name": "Bangun UI dashboard",
      "text": "Buat global filter, widget overdue, quick actions, dan audit trail agar workflow operasional lancar.",
      "url": "https://coderlegion.com/5893/fastapi-bgtasks-dashboard"
    },
    {
      "@type": "HowToStep",
      "name": "Tambah security & observability",
      "text": "Aktifkan RBAC, audit log, rate limiting, dan monitoring error/latency untuk produksi.",
      "url": "https://coderlegion.com/"
    }
  ]
}

Membangun Dashboard Monitoring Proyek Konstruksi dengan Python + FastAPI: Progress, RAB, dan Lapor

Tue, 24 Feb 2026 03:52:49 +0000

Dalam konstruksi modern, masalahnya jarang pada kurang data—yang sering terjadi adalah data terpencar: progres di lapangan ada di form harian, biaya ada di spreadsheet, material dan alat berat ada di catatan berbeda. Tren integrasi software konstruksi juga bergerak ke arah sistem yang saling “ngobrol” lewat API agar keputusan bisa diambil lebih cepat dan lebih akurat. Itulah kenapa gagasan dashboard monitoring proyek konstruksi makin relevan ketika kita ingin menyatukan progres, RAB, dan laporan harian ke satu sumber kebenaran (single source of truth), selaras dengan pembahasan tren integrasi pada artikel Construction Software Integration Trends for 2026.

Dari sisi ilmiah, pendekatan real-time tracking dan visualisasi data lintas komponen proyek juga terbukti krusial untuk mengurangi keterlambatan notifikasi dan keputusan berbasis “feeling”. Studi Real-Time tracking and analysis in construction projects membahas tantangan data multi-sumber (BIM, platform manajemen proyek, jadwal, dan data site) serta dampaknya pada analisis proyek. Karena itu, tema ini layak diangkat untuk pembaca CoderLegion: bukan sekadar “bikin dashboard”, tapi membangun fondasi API yang rapi—yang bisa dipakai ulang untuk otomasi laporan, integrasi ERP, sampai project intelligence berbasis data.

Kesimpulan cepat: Dashboard yang “bagus tampilannya” belum tentu berguna. Yang membuatnya benar-benar dipakai adalah data pipeline yang bersih, API yang konsisten, dan definisi metrik yang disepakati sejak awal—baru setelah itu visualisasi jadi senjata.

1. Dari Laporan Harian ke API: Kenapa FastAPI Cocok untuk Proyek?

Bayangkan setiap site punya cara masing-masing untuk melaporkan progres: foto, catatan WhatsApp, Excel, atau form manual. Ketika semua itu masuk ke satu backend berbasis API, Anda dapat memvalidasi, menyatukan format data, dan mengekspor ke dashboard dengan ritme yang konsisten. FastAPI cocok karena cepat, modern, dan punya automatic docs (OpenAPI/Swagger) yang memudahkan kolaborasi lintas tim.

Apa yang Dimaksud “Monitoring” di Proyek Konstruksi?

Monitoring yang sehat itu bukan sekadar “berapa persen selesai”. Praktiknya biasanya memadukan:

Progress fisik: volume pekerjaan (m³, m², meter lari), bobot item, earned value sederhana.
Biaya: realisasi vs RAB, komitmen PO, biaya alat berat.
Produktivitas: output per jam/shift, downtime.
Kualitas & HSE: temuan, near miss, checklist.

Prinsip Desain API yang Bikin Dashboard Tidak “Berantakan”

Sebelum menulis endpoint, biasakan satu prinsip: dashboard itu “makan” data yang konsisten.

Gunakan resource-oriented endpoint: /projects, /daily-reports, /cost-ledger.
Tentukan versi API sejak awal (/v1/...).
Standarisasi format tanggal, timezone, dan unit.

Bacaan internal yang relevan untuk memperkuat “cara berpikir API”:

2. Arsitektur Minimalis yang “Siap Dipakai”: Data, Layanan, dan Dashboard

Agar artikel ini tidak berakhir di level konsep, kita bikin arsitektur yang realistis untuk tim kecil: satu API, satu database, dan satu layer agregasi untuk dashboard. Targetnya sederhana: dashboard monitoring proyek konstruksi yang dapat menampilkan progres, ringkasan biaya, serta laporan harian.

Komponen Arsitektur

FastAPI: pintu masuk data (input) dan penyedia data (output).
PostgreSQL: sumber data terstruktur.
Worker (opsional): untuk sinkronisasi/ETL ringan (mis. impor spreadsheet, parsing foto metadata).
Frontend dashboard: bisa React/Vue/Metabase/Superset—bebas. Fokus artikel ini di API.

Tabel: Data yang Perlu Dikumpulkan (Versi Praktis)

Domain	Contoh data	Sumber umum	Update	Risiko jika tidak rapi
Progres	volume, bobot item, % capaian	laporan harian, checklist	harian	% “ngambang”, sulit audit
Biaya (RAB)	budget item, realisasi	RAB, invoice, PO	mingguan/harian	cost overrun terlambat ketahuan
Material	jenis, kuantitas, lokasi	delivery note, stok	harian	shortage mendadak
Alat berat	jam kerja, downtime	log operator/telemetri	harian	produktivitas turun tanpa sebab

3. Model Data: Skema yang Tidak Membuat Anda Menyesal

Kunci dashboard bukan hanya query, tetapi skema yang memudahkan agregasi. Anda ingin bisa bertanya: “proyek A minggu ini progresnya berapa, biaya lari berapa, dan top 3 item penyebab deviasi?”

Entitas Inti yang Disarankan

projects: metadata proyek.
work_items: item pekerjaan (berat/bobot).
daily_reports: catatan harian per proyek.
daily_progress: detail progres per item per hari.
budget_items: struktur RAB.
cost_ledger: transaksi biaya (aktual).

Tip Praktis

Simpan unit dan koefisien di work_items agar konversi tidak dilakukan di sisi frontend.
Pisahkan “header laporan” dan “detail progres” agar update parsial tidak menyiksa.

4. Implementasi FastAPI: Endpoint yang Ramah Dashboard

Di bab ini, kita turunkan konsep jadi endpoint yang bisa langsung dimakan UI. Setiap endpoint harus punya tujuan yang jelas: input data atau output agregasi.

Endpoint Minimum (MVP)

POST /v1/projects — membuat proyek.
POST /v1/daily-reports — input laporan harian.
GET /v1/projects/{id}/dashboard — agregasi untuk dashboard.
GET /v1/projects/{id}/progress?from=...&to=... — time series progres.
GET /v1/projects/{id}/cost-summary — ringkasan biaya vs RAB.

Pola Response untuk Agregasi Dashboard

Gunakan response yang “siap render”, contoh:

kpis: progres total, deviasi biaya, burn rate.
charts: series harian/mingguan.
alerts: item deviasi paling besar.

Pro tip: untuk endpoint agregasi, simpan query berat di layer service + caching. Dashboard yang lambat = dashboard yang ditinggal.

Catatan tentang Background Task

Kalau Anda punya proses impor (mis. upload Excel RAB), Anda bisa pakai background task. Untuk inspirasi visibility task, lihat fastapi-bgtasks-dashboard di CoderLegion.

5. How-To: Dari Nol ke Dashboard Data-Ready (Step-by-Step)

Bab ini dibuat sengaja “taktis”, supaya Anda bisa meniru alurnya lalu menyesuaikan ke real project.

Langkah 1 — Definisikan KPI yang Disepakati di Lapangan

Checklist KPI yang biasanya relevan:

Progress plan vs actual (harian/mingguan)
Cost actual vs budget (per item & total)
Produktivitas alat berat (jam operasi vs downtime)
Lead time material (PO → datang)

Langkah 2 — Normalisasi Input Laporan Harian

Buat form digital (mobile-friendly). Minimal:

tanggal, cuaca, shift
item pekerjaan + volume
tenaga kerja
alat berat (jenis + jam)
material masuk
catatan kendala

Langkah 3 — Bangun API Kontrak yang Stabil

Gunakan:

validasi ketat (Pydantic)
idempotency key untuk submit ulang
error format konsisten

Langkah 4 — Buat Endpoint Agregasi untuk UI

Hindari “frontend mengolah semua data mentah”. UI sebaiknya konsumsi:

KPI ringkas
data chart
daftar deviasi

Langkah 5 — Terapkan Audit Trail

Konstruksi itu dunia audit. Simpan:

created_by, created_at, source
histori revisi laporan

6. Praktik Lapangan: Data Material & Alat Berat Biar Tidak Cuma Jadi Angka

Di proyek nyata, suplai material alam (tanah, batu, basecourse) dan rental alat berat sering jadi titik kebocoran biaya jika pencatatan tidak disiplin. Dashboard monitoring proyek konstruksi yang bagus harus bisa menjawab pertanyaan sederhana: “berapa yang masuk, dipakai untuk apa, dan dampaknya ke progres?”

Material: Hindari “Masuk Banyak, Hilang Pelan-Pelan”

Wajibkan nomor dokumen (delivery note/DO)
Catat lokasi drop dan penerima
Cocokkan volume dengan progres work item terkait

Alat Berat: Jam Kerja yang Mengubah Narasi Biaya

Catat jam operasi, jam standby, downtime
Simpan alasan downtime (menunggu material, breakdown, cuaca)
Hubungkan ke produktivitas per work item

7. SEO-Friendly, Admin-Friendly: Cara Menulis Agar Artikel “Nempel” di CoderLegion

CoderLegion menyukai tulisan yang terasa hands-on, punya struktur jelas, dan tidak mengawang. Agar konten Anda tidak tenggelam:

Buka dengan problem nyata + solusi teknis.
Sisipkan tabel/diagram alur.
Tambahkan FAQ yang menjawab keberatan umum.
Sertakan HowTo (seperti di atas) agar pembaca cepat praktik.

Dan yang paling penting: ulangi istilah utama secukupnya. Di artikel ini, dashboard monitoring proyek konstruksi sengaja dipakai beberapa kali sebagai konteks, bukan sekadar pengulangan.

FAQ

1) Apakah dashboard harus dibuat dengan React?

Tidak. Anda bisa memakai BI tools (Metabase/Superset) selama API Anda rapi. Yang penting adalah kontrak data.

2) Bagaimana kalau RAB masih berupa Excel?

Mulai dari impor terstruktur: mapping kolom → budget_items, lalu simpan versi (v1, v2) agar revisi RAB tidak merusak histori.

3) Data di lapangan sering tidak lengkap. Apa yang dilakukan?

Mulai dari “minimum viable reporting”: 5–7 field wajib. Lalu tambahkan disiplin lewat validasi dan feedback loop (dashboard menampilkan data kosong sebagai alert).

4) Apakah butuh IoT untuk alat berat?

Tidak wajib. Tapi kalau ada telemetri, simpan sebagai event time series dan agregasikan per shift/hari.

5) Apa metrik paling cepat memberi dampak?

Progress vs biaya per item pekerjaan. Itu paling cepat memunculkan deviasi yang bisa ditindak.

Closing: Dashboard yang Bekerja untuk Keputusan, Bukan Sekadar Tampilan

Sebagai penutup, ada kutipan yang relevan untuk budaya engineering yang berujung pada kualitas sistem dan data: “You build it, you run it.” — sebuah prinsip yang sering dikaitkan dengan Werner Vogels, CTO Amazon yang dikenal luas di ranah distributed systems dan cloud architecture. Artinya dalam bahasa Indonesia: “Kamu yang membangun, kamu juga yang menjalankan.” Dalam konteks artikel ini, maknanya sederhana: kalau tim membangun API dan dashboard, tim yang sama harus peduli pada kualitas data, performa endpoint, dan dampaknya pada operasi proyek—karena di sanalah feedback loop yang membuat dashboard monitoring proyek konstruksi benar-benar dipakai.

Jika Anda ingin melihat bagaimana pendekatan ini dipakai di proyek nyata—mulai dari konstruksi sipil/struktur, MEP, suplai material alam, sampai rental alat berat—kami membuka ruang diskusi dan kolaborasi. Kunjungi profil perusahaan kami di PT Abi Darma Sejahtra untuk melihat layanan dan portofolio.

{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "Membangun Dashboard Monitoring Proyek Konstruksi dengan Python + FastAPI",
  "description": "Panduan membangun API berbasis FastAPI untuk menyuplai data progres, RAB, dan laporan harian ke dashboard monitoring proyek konstruksi.",
  "totalTime": "PT6H",
  "supply": [
    {"@type": "HowToSupply", "name": "Dataset laporan harian (CSV/Google Form/Spreadsheet)"},
    {"@type": "HowToSupply", "name": "Struktur RAB (Excel/CSV)"}
  ],
  "tool": [
    {"@type": "HowToTool", "name": "Python 3.10+"},
    {"@type": "HowToTool", "name": "FastAPI"},
    {"@type": "HowToTool", "name": "PostgreSQL"}
  ],
  "step": [
    {
      "@type": "HowToStep",
      "name": "Definisikan KPI proyek",
      "text": "Tetapkan KPI yang disepakati (progress plan vs actual, biaya vs RAB, produktivitas alat, lead time material) agar dashboard punya tujuan yang jelas.",
      "url": "https://www.abidarmasejahtra.co.id/"
    },
    {
      "@type": "HowToStep",
      "name": "Normalisasi format laporan harian",
      "text": "Buat format input minimal yang konsisten: tanggal, shift, item pekerjaan, volume, alat, material, dan kendala. Terapkan validasi agar data siap diproses.",
      "url": "https://coderlegion.com/11707/best-practices-for-restful-api-design-for-dev-tools"
    },
    {
      "@type": "HowToStep",
      "name": "Bangun kontrak API versi pertama",
      "text": "Rancang endpoint resource-oriented, gunakan versioning (/v1), format error konsisten, dan idempotency key untuk menghindari duplikasi submit.",
      "url": "https://coderlegion.com/4597/versioning-your-api-the-right-way-rest-best-practices"
    },
    {
      "@type": "HowToStep",
      "name": "Buat endpoint agregasi dashboard",
      "text": "Sediakan endpoint khusus agregasi KPI, time series chart, dan daftar deviasi agar frontend tidak mengolah data mentah secara berlebihan.",
      "url": "https://cmicglobal.com/resources/article/construction-software-integrations-trends"
    },
    {
      "@type": "HowToStep",
      "name": "Tambahkan audit trail dan kontrol kualitas data",
      "text": "Simpan created_by/created_at, histori revisi laporan, dan lakukan pemeriksaan silang volume material vs progres. Gunakan caching untuk respons dashboard yang cepat.",
      "url": "https://www.sciencedirect.com/science/article/pii/S1474034625004045"
    }
  ]
}

Building a Production-Ready Ecommerce Backend with FastAPI

Sun, 18 Jan 2026 08:03:04 +0000

When learning backend development, most projects stop at CRUD APIs.
I wanted to go a step further and build a realistic ecommerce backend—one that follows industry practices, not shortcuts.

This blog walks through what I built, why I built it that way, and the key backend concepts involved.

Project Goal

To design a secure, scalable ecommerce backend that handles:

Authentication
Cart management
Checkout flow
Orders
Payments
Stock consistency
Password recovery
All while following real-world backend design principles.

Tech Stack

FastAPI – high-performance Python API framework
SQLAlchemy – ORM for database modeling
PostgreSQL – relational database
Alembic – database migrations
JWT – authentication
bcrypt – password hashing

Authentication & Security

Passwords are never stored in plain text.
Passwords are hashed using bcrypt
JWT is used for authentication
Password recovery is handled via secure, time-bound reset tokens
No password is ever decrypted or sent back to users
Password recovery is implemented by resetting, not revealing passwords.

Cart Design (Temporary State)

The cart is designed as a mutable, temporary state:

Users can add, update, or remove items
Only one active cart per user
Prices are snapshotted at the time of adding to cart
This prevents price mismatch issues during checkout.

Checkout (State Transition)

Checkout is a critical boundary:

Converts a cart into an immutable order
Validates stock
Calculates final price
Creates a PENDING order
Cart represents intent.
Checkout represents commitment.

Orders (Immutable Records)

Orders are treated as financial records:

Created only via checkout
Read-only for users
Status-based lifecycle: PENDING → PAID → CANCELLED
This ensures auditability and consistency.

Payments (Asynchronous & Safe)

Payments are handled separately from checkout:

Payment intents are created for orders
Payments are confirmed asynchronously
Stock is reduced only after payment success

This avoids overselling and handles real payment gateway behavior.

Stock Management

Stock updates are protected using row-level locking to avoid race conditions during concurrent purchases.

Stock is reduced only after confirmed payment—not during checkout.

API Documentation

Swagger (OpenAPI) is fully integrated:

Cleanly grouped APIs
Request & response schemas
JWT authorization support
Ready for frontend or third-party integration

Database Migrations

All schema changes are managed via Alembic migrations
No manual DB edits
Reproducible environments
Safe schema evolution

What I Learned

Why carts and orders must be separate
Why payments must be asynchronous
Why passwords must be irreversible
How ORM relationships fail if not symmetric
How real-world ecommerce systems prevent overselling

Source Code

The complete project is available on GitHub:
https://github.com/sanjay-dot/Ecommerce

Final Thoughts

This project helped me move from API writing to system thinking.

If you’re learning backend development, I highly recommend building projects that:

model real workflows
enforce correct state transitions
prioritize security from day one

fastapi-bgtasks-dashboard

Thu, 02 Oct 2025 10:33:13 +0000

One of the great things about FastAPI is how easily you can offload work to background tasks with BackgroundTasks. But once tasks are fired off, they often disappear into a black box and you don’t know if they’re still running, when they’ll finish, or whether they failed silently.

That’s where fastapi-bgtasks-dashboard comes in. It’s a lightweight, plug-and-play dashboard SDK that gives FastAPI developers real-time visibility into their background tasks. With just a one-liner, you can embed a live dashboard in your app and instantly see what your background workers are doing.

Transparency – Monitor queued, running, and completed tasks at a glance.
Zero overhead – Designed to be minimal and fast, so it won’t slow down your API.
Plug-and-play – Simple integration with your existing FastAPI project.
Developer-friendly – Debug issues and optimize background job handling in development or production.

This tool was born out of real-world needs while building scalable financial backends. Developers often struggled with invisible background jobs, making debugging painful. By adding this dashboard, your team gets confidence and control over background processing without adding Redis, Celery, or other heavyweight dependencies.

I’m sharing this project with the FastAPI ecosystem because I believe observability should be simple. If you find fastapi-bgtasks-dashboard useful:

⭐ Give it a star on GitHub to help others discover it.
Contribute ideas, bug fixes, or new features.
Consider sponsoring to support ongoing improvements and maintenance.

Together, we can make the FastAPI ecosystem even more developer-friendly by solving everyday pain points in a clean, open-source way.

FastAPI Error Handling in Python: Unify Responses with APIException

Sun, 24 Aug 2025 09:43:32 +0000

[SPOILER ALERT] Watch how a messy error handling system transforms into a clean, unified API in under a minute. Quick Demo Video

APIException: from chaos to clean, predictable API responses.

While working with FastAPI for quite a long time, I kept running into a couple of annoying problems that occurred in almost all projects I started with FastAPI.

Don’t get me wrong because of what I said above; I’m a big FastAPI fan and have been using it for over 4 years in almost all my projects.

It’s still my go-to framework for backend development. But like any tool, there are small pain points that start to pile up over time.

Nothing major at first glance, but these issues caused headaches for frontend integration, documentation, and even debugging.
Let’s break them down one by one.

Problem 1 – Inconsistent Response Formats

Anyone who has spent some time with FastAPI knows that, by default, responses vary depending on the error type:

// Endpoint 1 error
{"error": "User not found"}

// Endpoint 2 validation [422] error
{"detail": [{"loc": ["body", "name"], "msg": "field required"}]}

// Unhandled exception
<html>...HTML error page...</html>

This means:

422 Validation errors return Pydantic’s default format
HTTPExceptions have a different JSON structure
Unhandled exceptions may even return HTML
Also, they don’t look great on Swagger. Some aren’t even documented by default.

This is frustrating for API consumers because they need to handle multiple formats for different error types.

Problem 2 – Registering Exception Handlers in Every App is a Pain

If you work on multiple projects at the same time, you quickly realise that setting up everything you’ve already done in previous projects for each new one gets old fast.

from fastapi import FastAPI, HTTPException, Request
from fastapi.responses import JSONResponse
from fastapi.exceptions import RequestValidationError
import logging

logger = logging.getLogger(__name__)

app = FastAPI()

@app.exception_handler(HTTPException)
async def http_exception_handler(request: Request, exc: HTTPException):
    logger.error(f"HTTPException: {exc.detail}")
    return JSONResponse(
        status_code=exc.status_code,
        content={"error": exc.detail},
    )

@app.exception_handler(ValueError)
async def value_error_handler(request: Request, exc: ValueError):
    logger.error(f"ValueError: {str(exc)}")
    return JSONResponse(
        status_code=400,
        content={"error": str(exc)},
    )

@app.exception_handler(RequestValidationError)
async def validation_exception_handler(request: Request, exc: RequestValidationError):
    logger.error(f"Validation error: {exc.errors()}")
    return JSONResponse(
        status_code=422,
        content={"error": exc.errors()},
    )

For every app you build, you have to:

Register exception handlers
Ensure the response format remains consistent across all exceptions
Repeat the same boilerplate code over and over again
And yes... It's boring, and I hate it.

Problem 3 – The Repetitive Code You Keep Writing in Every Endpoint At Least Once

In many FastAPI projects, I often see (and used to write) error handling like this:

if some_event:
    logger.error("User not found")
    raise HTTPException(detail="User not found", status_code=404)

I believe that every exception should be logged in most projects, unless you have intentionally configured it not to log a specific error.

The Goal

In short, the goal is to solve the problems described above using fewer lines of code while maintaining the same functionality, adding no extra overhead, and causing no performance issues.

I wanted a solution that would:

A single unified response schema for all cases (success or exception/error)
Swagger/OpenAPI docs to reflect all possible responses
Unhandled exceptions to return clean JSON
Automatic logging unless you explicitly disable it

Solutions

I've created a Python package called APIException that includes solutions for problems described above and more...

Documentation is clear and suggested.

Installation

You can install it directly via pip:

pip install apiexception

And you can import it:

import api_exception

Once you have it installed, you're good to go.

1) The Solution for Problem - 1: Unified ResponseModel

One of the biggest things I wanted was for every single API response, whether it’s a success or an error, to have the exact same JSON format.
So, here’s what I did: I created a ResponseModel that every single endpoint and every single exception in the app will use.

Why do I think that using `ResponseModel` is awesome?

When the response format is standardised for both success and error cases, the frontend integration becomes a breeze.

The frontend team always knows the API will return the same structure, so after parsing the JSON, it can simply check the status field:

If status is "SUCCESS" → grab the payload from the data field.
If status is "FAIL" → check the error_code.
- From there, the frontend can either use its own custom error message or use the message or description fields returned by the API.
- The description and message fields can also serve different purposes in success cases (for example, human-readable info or debugging context).

Example: Before & After using `ResponseModel` in FastAPI router's `response_model`

Before:

{"error": "User not found"}
{"detail": [{"loc": ["body", "name"], "msg": "field required"}]}
<html>...HTML error page...</html>

After – Error Case (APIException)

{
  "data": null,
  "status": "FAIL",
  "error_code": "USR-404",
  "message": "User not found.",
  "description": "The user ID does not exist."
}

After – Error Case (Unhandled Exception)

{
  "data": null,
  "status": "FAIL",
  "error_code": "SRV-500",
  "message": "Internal Server Error",
  "description": "An unexpected error occurred."
}

After – Success Case

{
  "data": {
    "id": 1,
    "name": "John Doe"
  },
  "status": "SUCCESS",
  "error_code": null,
  "message": "Operation completed successfully.",
  "description": "User gathered successfully."
}

I believe that the above ResponseModel described above is cleaner, more consistent, and makes things easier for both backend and frontend teams. The backend team will always know the error_code, which makes it easier to find bugs from the logs, while the frontend team can handle responses much more efficiently. They no longer need to check if the http_status_code is 20x and then parse the response. Instead, they can simply parse the response once, check the status parameter to determine whether it is a success or error, and then look at either the data parameter or the error_code parameter accordingly.

2) The Solution for Problem - 2: APIException

Another major improvement I wanted was to avoid writing repetitive logging code in every endpoint before raising exceptions.
With APIException, all exceptions are automatically logged unless you explicitly disable logging for a specific error.

This means you can replace code like this:

if not user:
    logger.error("User not found")
    raise HTTPException(status_code=404, detail="User not found")]

With a much cleaner and shorter version:

from api_exception import APIException, BaseExceptionCode

class CustomExceptionCode(BaseExceptionCode):
    USER_NOT_FOUND = ("USR-404", "User not found.", "The user ID does not exist.")

if not user:
    raise APIException(ExceptionCode.USER_NOT_FOUND)

Using APIException together with a CustomExceptionCode that extends your BaseExceptionCode not only makes logs easier to read, but also creates a reusable structure for handling repeated exception messages. When you used APIException together with a CustomExceptionCode it automatically provides the error_code, message, and description from there. So define your own custom exception class and make the backend more consistent in terms of logging and code repetition.

When raised, APIException will:

Automatically log the error with the provided error_code, message, and description
Return a unified response format (via ResponseModel)
Optionally disable logging for certain exceptions (e.g., log=False if you don’t want it logged)
Optionally you can add extra log message by using log_message: [str | dict] parameter.

3) The Solution for Problem - 3: One-Time Handler Registration with register_exception_handlers

Instead of adding exception handlers all over the place and duplicating app.add_exception_handler(...) calls,
I wanted a single entry point to set up my API’s exception handling.
That’s exactly what register_exception_handlers does.

When you call it, it:

Attaches APIException handlers so all your APIException raises return the same format.
Optionally adds a fallback middleware to catch all unhandled exceptions (like runtime errors, DB failures, or 3rd-party API crashes).
Ensures consistent logging:
- Always logs error_code, message, description.
- Can log full tracebacks for handled errors or only for unhandled ones.
Supports multiple response formats:
- ResponseModel (your unified API response structure)
- RFC7807 (Problem Details for HTTP APIs)
- dict (plain JSON dicts)
Can decide if null fields are included in OpenAPI docs or hidden.
Centralizes all logging options in one place.

Why it’s great:

I don’t have to remember to register handlers in every new project.
I can switch response formats for the whole API in one line.
Logging behavior is configurable without touching the actual endpoints.
It keeps my project clean and DRY.

Example – minimal setup:

from fastapi import FastAPI
from api_exception import register_exception_handlers

app = FastAPI()
register_exception_handlers(app)

Example:

from fastapi import FastAPI
from api_exception import (
    register_exception_handlers,
    ResponseFormat,
    logger
)

app = FastAPI()
  #You can set different log levels. `default="WARNING"`
logger.setLevel("DEBUG")

  #Default settings are provided below.

register_exception_handlers(
    app=app,
    response_format=ResponseFormat.RESPONSE_MODEL,
    use_fallback_middleware=True,
    log_traceback=True,
    log_traceback_unhandled_exception=True,
    include_null_data_field_in_openapi=True,

    # v0.2.0 new features 
    log_level="ERROR",                        # override verbosity for exception logs
    log_request_context=True,                 # include request headers in logs
    log_header_keys=("x-request-id", "user-agent"),
    extra_log_fields={"service": "user-api"}, # inject structured metadata
    response_headers=("x-user-id",),          # echo back specific headers in response
)

“Copy-Paste" Example

Below is a minimal, end-to-end example showing:

one unified ResponseModel for success and errors
global handler registration with register_exception_handlers which let's you auto log, show tracebacks for both APIException and unhandled exceptions such as db or third party errors. Moreover, the ResponseFormat will be ResponseModel.
a custom exception code set via BaseExceptionCode
how unhandled exceptions are caught and shaped the same way

from typing import List
from fastapi import FastAPI, Path
from pydantic import BaseModel, Field
from api_exception import (
    APIException,
    BaseExceptionCode,
    ResponseModel,
    register_exception_handlers,
    APIResponse,
    logger,
)

app = FastAPI()

 #1) Register once → consistent responses + logging everywhere
register_exception_handlers(app=app)

 # Optional: set a different log level for 'apiexception'
logger.setLevel("DEBUG")

 #2) Define your custom exception codes (clean logs, reusable messages)
class CustomExceptionCode(BaseExceptionCode):
    USER_NOT_FOUND = ("USR-404", "User not found.", "The user ID does not exist.")
    INVALID_API_KEY = ("API-401", "Invalid API key.", "Provide a valid API key.")
    PERMISSION_DENIED = ("PERM-403", "Permission denied.", "Access to this resource is forbidden.")

 #3) Your domain models
class UserModel(BaseModel):
    id: int = Field(...)
    username: str = Field(...)

class UserResponse(BaseModel):
    users: List[UserModel] = Field(..., description="List of user objects")

 #4) An endpoint that returns unified responses in all cases
@app.get(
    "/user/{user_id}",
    response_model=ResponseModel[UserResponse],
    responses=APIResponse.default(),
)
async def user(user_id: int = Path(..., description="The ID of the user")):
    # Handled error example (uses your code+message+description and logs it)
    if user_id == 1:
        raise APIException(
            error_code=CustomExceptionCode.USER_NOT_FOUND,
            http_status_code=404,  # or 401 if you prefer
        )

    # Unhandled error example (still unified + logged)
    if user_id == 3:
        a = 1
        b = 0
        c = a / b   # ZeroDivisionError,caught by fallback, same JSON shape
        return c

    # Success case (same structure, frontend always reads status+data)
    users = [
        UserModel(id=1, username="John Doe"),
        UserModel(id=2, username="Jane Smith"),
        UserModel(id=3, username="Alice Johnson"),
    ]
    data = UserResponse(users=users)
    return ResponseModel[UserResponse](
        data=data,
        description="User found and returned.",
    )

After running the above app, you will have the swagger documentation as in the video below.

Click to Watch The Video

When the app raise APIException, the exception will be logged as below by default:

When the app raise unexpected error such as a ZeroDivisionError, a database connection failure, or a third-party API timeout, the exception will be logged as below by default:

What’s New in v0.2.0

The v0.2.0 release focused on making exception handling even more flexible and logging more powerful:

Added

Advanced logging customizations in register_exception_handlers:
- log_level: override verbosity for exception logging.
- log_request_context: toggle to include/exclude request headers in logs.
- log_header_keys: define which headers are logged (default: x-request-id, user-agent, etc.).
- extra_log_fields: inject custom structured metadata into logs (e.g. user_id, masked API keys).
Response headers echo in register_exception_handlers:
- response_headers=True → default headers echoed back.
- response_headers=False → no headers echoed.
- response_headers=("x-user-id",) → custom headers echoed.
APIException now accepts header parameters (responses can carry custom headers).
Mypy support for static type checking.
Extended docs with logging patterns and advanced usage examples.

Changed

Logging format revamped → now more structured, readable, and consistent.
Error logs enriched with request path, method, client IP, HTTP version, etc.

Fixed

Swagger/OpenAPI now shows consistent error schemas even when data was missing.
File structure cleanup → simplified imports in __init__.py.
Type hint fixes for error_code as BaseExceptionCode.

Upgrade now:

pip install apiexception --upgrade

Performance Impact

I wanted to make sure this solution would not slow down the API.
So, I ran a simple benchmark with 200 concurrent users and compared it to FastAPI’s built-in HTTPException:

fastapi.HTTPException → 2.00 ms
api_exception.APIException → 2.72 ms

That’s only +0.72 ms difference, when you think that HTTPException doesn't log the exceptions however APIException does log the exceptions that occur in the app so the difference is fair for me.

Community recognition

The library was featured on Python Weekly #710, one of the largest Python newsletters worldwide.
It also reached #3 in r/FastAPI’s pip-package flair on Reddit.

This kind of feedback and visibility motivates me to keep improving APIException and adding more features for the community.

Why I Think This Matters

Frontend developers love it because they can handle every response the same way.
Backend developers love it because debugging is easier with consistent logs.
QA testers love it because error states are predictable.
API consumers love it because the docs clearly show all response shapes.

If this resonates with you, give it a quick spin:

Install: pip install apiexception
Register: register_exception_handlers(app)
Define codes: extend BaseExceptionCode from api_exception
Success: return ResponseModel[...]
Errors: raise APIException(...)
Docs: add APIResponse.default() to your routes → makes Swagger docs much cleaner

I’m actively improving the library—feedback, issues, and PRs are very welcome. And if it saves you some time (it probably will), a GitHub star would mean a lot.

Links

GitHub: https://github.com/akutayural/APIException
Docs: https://akutayural.github.io/APIException/
PyPI: https://pypi.org/project/apiexception/

Securing ASGI Server with AWS Cognito

Thu, 20 Feb 2025 19:02:49 +0000

Introduction

I published an article on hash node a couple weeks ago titled: [Deploying Complete Serverless API with any containerised Python ASGI Framework on AWS Lambda, API][1]

I figured I needed to add a logical next step to securing the api. I was also partly inspired by the course by Steven Marek towards AWS Solutions Architect Certification, which I'm studying.

/src_code

The GitHub code repo for this project is here: https://github.com/652-Animashaun/blog-serverless.git

Its written in Python - FastAPI, deployed to AWS Lambda, then put an API Gateway in front to route client requests to appropriate endpoints. That's it you're all caught up.

While code example used here is Fast API framework, I implore you the implementation discussed is python framework agnostic. Come on I'll show you.

What is AWS Cognito?

I must admit the AWS Cognito documentation gave me the run around. I spent way more time than I thought I should implementing this mechanism. I'm not all that new to JWT authentication. I've implemented mechanisms using the OAuth before.
Anyways I’ve done the work, gone through the belly of the beast that is the AWS documentation, so that you won’t have to. I’ll try to cut out the fluff.

Amazon Cognito is an identity platform for web and mobile apps. It’s a
user directory, an authentication server, and an authorization service
for OAuth 2.0 access tokens and AWS credentials. With Amazon Cognito,
you can authenticate and authorize users from the built-in user
directory, from your enterprise directory, and from consumer identity
providers like Google and Facebook.

So off the bat, we can already see several use cases for the AWS Cognito service. For now we want a simple authentication process, i.e user is served a login page to enter credentials, redirected to homepage on successful login, or presented a register page to create an account get OTP via provided email to verify ID. They get a token (JWT) which is presented to the server’s gate keeper for some resource access, in this case an API endpoint.
What is happening under the hood is simple enough too. Well relatively, if you compare to implementing the mechanism from scratch.

User authentication with Cognito user pools

Login & Register Pages - Cognito

While you can build and customise to your liking, but AWS Cognito comes with a ready-to-use login and register pages where you can just redirect users to, you’ll also provide a redirect url where the returned token can be processed to authorize user.

Sending & Verifying OTP - Cognito

Usually one would be inclined to use a service like SES or SNS on AWS or Twilio, but you’ll have to manually call or implement the mechanism from the server side. AWS cognito takes care of this out of the box.

Encoding & Signing Tokens - Cognito

Cognito also takes care of encoding tokens. RS256 or HS256 base64encoding, also add features like expiry, a refresh token if you want. A Json Web Token contains 3 parts header, payload and a signature. Payload is where the user identity like email, username are returned. Cognito returns 3 tokens, the access_token, id_token and a refresh_token, more about that later.

Decoding and Granting Access - Server

When a token is returned to the server, the receiver of the JWT verifies the signature using the secret key or the public key. And maybe go a step further and include it in request header so that subsequent requests can bear the authorisation token.

Look, point is Cognito takes a lot of manual implementation out of the developers hand. I’m sold!.

Let's dive right into the AWS Cognito dashboard create a user pool in 3 steps.

Creating and configuring a user pool

Select Create user pool from the User pools menu, or select Get started for free in less than five minutes.

Under Define your application, I’m choosing “traditional web application” you can choose the Application type that best fits the application scenario that you want to create authentication and authorization services for.

In Name your application, enter a descriptive name or proceed with the default name.

You must make some basic choices under Configure options that support settings that you can't change after you create your user pool. For this use case I’m selecting username, email and full name.

Add a return url on the server that handles payload receipts and process the payload. in this case mine is http://localhost:8000/api/v1/users/token for development and testing purposes. You can add more redirect url options. Once you're ready to update lambda function with local changes, we'll be sure to add another return url , this time with the API Gateway stage endpoint. Else we get some funny error client_id redirect_uri mismatch. Hit create.

Web App Server

Lets take a look in the user pool thats just been created:

Under recommendations you should go ahead and click “setup your web app”.

AWS was kind enough to show some code examples for different languages.

Selecting python will give you a quick preview how things would look like:

As shown, the framework in Cognitgo example is Flask, but it doesnt matter, that about how we’ll be implementing ours. I can already see that to start with I’ll need a /login endpoints and an /authorize endpoints at a minimum.

/app.api.enpoints.users.py

import os
import jwt
from pprint import pprint
from fastapi import APIRouter, HTTPException, status, Depends
from starlette.requests import Request
from app.utils.auth import oauth, verify_token
from starlette.responses import RedirectResponse

router = APIRouter()

@router.get("/login")
async def login(request: Request):
    return await oauth.oidc.authorize_redirect(request, "http://localhost:8000/api/v1/users/token")

@router.get("/token")
async def authorize(request: Request):
    payload = await oauth.oidc.authorize_access_token(request)
    token = payload["id_token"]
    res = await verify_token(token)
    user = payload["userinfo"]
    return token

These endpoints aren’t doing much heavy lifting. /login simply calls on oidc.authorize_redirect() provided by the oauth import from utils where OAuth was instanced and passed to oauth, more on that subsequently. It takes a request and a redirect url to process response.

async def authorize(request) will receive a get request on signing completion on cognito, with a json payload that looks like:

{ "id_token": "eyJraWQiOiJ3ekxUT1lrNVR....", "access_token": "eyJraWQiOiI3b0pqeFhY...", "refresh_token": "eyJjdHkiOiJKV1QiLC....", "expires_in": 3600, "token_type": "Bearer", "expires_at": 1738976151, "userinfo": { "at_hash": "aYWSJq...", "sub": "b4d8e428-f091-7040-80a5-f2", "email_verified": true, "iss": "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ftTN1aEr4", "cognito:username": "shaun", "nonce": "SYqZdIip5wBjjI10983", "origin_jti": "edc6ytb3c-4870-4979-8672-7d9a261ff471", "aud": "47re0a7e8l43ok719rtqcqnjih", "token_use": "id", "auth_time": 1738972551, "exp": 1738976151, "iat": 1738972551, "jti": "f20cf2a4-5c3f-44f9-8d0b-919816d41f38", "email": "*Emails are not allowed*" } }

As seen above we can already grab userinfo and quickly see the user ID. But theoretically some skilled man in the middle can provide their own ID, I dont know how it's done, the main thing is it is possible. And I like to preempt that, I want to do a quick verify.

import os
import jwt
from jwt import PyJWKClient
from authlib.integrations.starlette_client import OAuth
from fastapi import APIRouter, HTTPException, status, Depends, Security, HTTPException
from datetime import date, datetime, time, timedelta, timezone
from typing import Annotated
from app.models.users import User
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials, OAuth2PasswordBearer
from starlette.responses import RedirectResponse
from starlette.requests import Request


signin_url = 'https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ftTN1aEr4/.well-known/jwks.json'
security = HTTPBearer(auto_error=False)

CLIENT_SECRET = os.environ["CLIENT_SECRET"]
CLIENT_ID = os.environ["CLIENT_ID"]
ISSUER = "https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ftTN1aEr4"


oauth = OAuth()
oauth.register(
  name='oidc',
  authority=ISSUER,
  client_id=CLIENT_ID,
  client_secret=CLIENT_SECRET,
  server_metadata_url='https://cognito-idp.us-east-1.amazonaws.com/us-east-1_ftTN1aEr4/.well-known/openid-configuration',
  client_kwargs={'scope': 'email openid phone'}
)

async def verify_token(token:str)-> User:
jwks_client = PyJWKClient(signin_url)

try:
signing_key = jwks_client.get_signing_key_from_jwt(token)
payload = jwt.decode(
token,
signing_key,
audience=CLIENT_ID,
options={"verify_exp": True},
algorithms=["RS256"],
)
user = User(username=payload["cognito:username"], email=payload["email"], access_token=token)
return User
except jwt.ExpiredSignatureError:
raise HTTPException(status_code=401, detail="Token has expired")
except jwt.InvalidTokenError as e:
raise HTTPException(status_code=403, detail="Invalid token")

async def get_current_user(credentials: Annotated[HTTPAuthorizationCredentials, Security(security)]):
if not credentials:
return False
try:
return await verify_token(credentials.credentials)
except HTTPException:
return False

Lets do a quick run through the code:

The singing_url is provided by congnito in the userpool dashboard, this an endpoint provided by Cognito. At the back of it is a json_body of keys used to sign the token. More on that subsequently.

In FastApi using Oauth2 as dependency is through the Security() class provided. You can read more about the stuff here. TLDR fastapi.security.HTTPBearer is one of the tools provided to use called as a dependable during visit of protect endpoints. It’s use case is for bearer token authentication. auto_error=False because as per docs, by default, if the HTTP Bearer token is not provided (in an Authorization header), it'll automatically cancel the request and send the client an error. I don’t want that, I want to catch that and redirect to login so user can try challenge again.

HTTPBearer returns an object HTTPAuthorizationCredentials which I believe is received via the request header and provides it to the application.

Then we just shamelessly copied the boiler plate code on cognito recommendation page to instantiate Oauth.register().

async def verify_token() will take in a token, first it want’s to retrieve signing keys from the signing_url using the python module PyJWKClient class provided by JWT module. Next it calls jwt.decode(), takes the token, signing_key and a couple other keyword arguments. The decoded payload contains a dictionary with several user identifying information, but it’ll go ahead, returning username and email.

In async def get_current_user() where the first injection takes place. I’ve provided the HTTPAuthorizationCredentials as HTTPBearer security which would try to retrieve the automaticall from the incoming request header the Bearer Authorization this is where the token is expected to be for an authenticated request.

/app.api.endpoints.posts.py

To show the authentication mechanism actually works we have to create an endpoint that is protected:

from fastapi import APIRouter, Depends, HTTPException, status
from typing_extensions import Annotated
from app.utils.auth import oauth, verify_token, get_current_user
from app.models.users import User
from starlette.requests import Request
from starlette.responses import RedirectResponse

router = APIRouter()

@router.get("/")
async def all_posts(current_user: Annotated[User, Depends(get_current_user)]):
    if not current_user:
        return RedirectResponse(url="/api/v1/users/login")
    print("current_user", current_user)
    return {"Welcome": "Shaun's Blog", "user": current_user}

Pretty straightforward right? async def all_posts depends on get_current_user which in turns returns a user object or None, in which case user will be redirected to /login.

Oh did I mention and AWS Cognito is free for 10K monthly active users. Check it out:

Amazon Cognito Essentials and Lite have a free tier. The free tier
does not automatically expire at the end of your 12-month AWS Free
Tier term, and it is available to both existing and new AWS customers
indefinitely. Please note - the free tier pricing isn’t available in
the AWS GovCloud (US-West) region.

For users who sign in directly via Amazon Cognito or through a social identity provider, Amazon Cognito user pools has a free tier of
10,000 monthly active user (MAU) per month per account or per AWS
organization. This free tier is applicable for customers that
configure their user pools to either the Lite or Essentials tier.
There is no free tier for the Plus tier.

Stick around next one up is integrating social ID providers like google social media accounts. Would be fun.

One more thing, remember when you push changes to lambda, add the api gateway endpoint version of your /token (authorise) to the list of return urls in the Cognito UserPool dashboard. This might be the cause of client_id redirect_uri mismatch error, watch out.

References:

https://docs.aws.amazon.com/cognito/latest/developerguide/getting-started-user-pools-application.html

https://pyjwt.readthedocs.io/en/stable/installation.html

When to Choose FastAPI Over Django or Flask: A Comprehensive Guide with Practical Examples

Wed, 22 Jan 2025 10:22:44 +0000

Python is home to several powerful web frameworks, each designed to cater to different needs. Django and Flask have long been dominant players, offering solutions for web development for over a decade. However, in recent years, FastAPI has emerged as a modern framework, purpose-built for APIs and asynchronous programming. Its speed, simplicity, and robust features make it an appealing choice for developers.

In this guide, we’ll explore:

What makes FastAPI unique.
Key differences compared to Django and Flask.
Specific use cases where FastAPI excels.
Detailed examples demonstrating its strengths.

What is FastAPI?

FastAPI is a Python framework for building APIs with modern design principles. It’s built on the Starlette framework (for the web parts) and Pydantic (for data validation). Unlike Django or Flask, FastAPI fully embraces asynchronous programming with asyncio, making it one of the fastest Python frameworks available.

Key Features:

High Performance: Comparable to Node.js and Go, thanks to ASGI and
async support.
Automatic Documentation: Swagger UI and ReDoc are auto-generated.
Type Safety: Input validation and response types are built-in using
Python's type hints.
Ease of Use: FastAPI is simple to use, even for beginners, while
offering powerful capabilities for experts.

Why Choose FastAPI?

FastAPI is specifically designed for building modern APIs with a focus on performance and developer experience. Let’s delve deeper into scenarios where it outshines Django and Flask:

1. High-Performance APIs
If your application needs to handle thousands of simultaneous requests efficiently, FastAPI is a game-changer.

Built on ASGI, it supports asynchronous requests out of the box.
Ideal for real-time applications, such as chat servers, streaming
platforms, or IoT systems.

Example: Asynchronous API with FastAPI

from fastapi import FastAPI
import asyncio

app = FastAPI()

@app.get("/long-task/")
async def long_task():
      await asyncio.sleep(5)  # Simulate a time-consuming operation
      return {"message": "Task completed after 5 seconds"}

This endpoint:

Demonstrates how FastAPI handles concurrent requests without blocking
other users.
Would be cumbersome to implement in Flask or Django without
significant modifications.

2. Automatic Documentation

FastAPI automatically generates Swagger UI and ReDoc documentation for your API. This is a huge time-saver for teams working on complex APIs.

Example: Auto-Generated Docs

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")
async def read_item(item_id: int, q: str = None):
"""
Fetch an item by ID.

  - **item_id**: The ID of the item to fetch.  
  - **q**: An optional query string for filtering results.  
"""
    return {"item_id": item_id, "query": q}

To access the docs:

Run the app using uvicorn:

uvicorn main:app --reload

Visit:

Swagger UI: http://127.0.0.1:8000/docs
ReDoc: http://127.0.0.1:8000/redoc

Both provide an interactive interface to test your API endpoints.

3. Data Validation and Serialization

FastAPI uses Pydantic for data validation, which ensures robust type checking and error handling.

Example: Input Validation with Pydantic

from fastapi import FastAPI
from pydantic import BaseModel

app = FastAPI()

class User(BaseModel):
    username: str
    email: str
    age: int

@app.post("/users/")
async def create_user(user: User):
    return {"message": "User created successfully!", "user": user}

What happens here:

FastAPI automatically validates that the username, email, and age
fields are present and of the correct type.
If validation fails, the API returns a detailed error message
without any extra coding.

4. WebSocket Support

Real-time communication is a breeze with FastAPI, thanks to native WebSocket support.

Example: Building a WebSocket Chat Server

from fastapi

import FastAPI, WebSocket

app = FastAPI()

@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    while True:
        data = await websocket.receive_text()
        await websocket.send_text(f"You said: {data}")

Use this for:

Chat applications.
Real-time notifications or dashboards.
Multiplayer games.

5. Ease of Scaling and Deployment

FastAPI integrates well with modern deployment tools like Docker and Kubernetes. Its ASGI compatibility makes it ideal for scaling microservices.

Example: Dockerizing FastAPI

FROM python:3.10-slim

WORKDIR /app
COPY requirements.txt requirements.txt
RUN pip install -r requirements.txt
COPY . .

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

When Django or Flask Might Be Better

Django is unbeatable for full-stack applications with templates,
authentication, and ORM out of the box.
Flask is perfect for small projects or when you need a quick
prototype without the complexity of Django or FastAPI.
Legacy Systems: If your team already uses Django or Flask
extensively, switching to FastAPI might not justify the learning
curve.

Tip: When starting with FastAPI, use Uvicorn as your ASGI server for a smooth development experience. It’s lightweight, easy to configure, and perfectly complements FastAPI’s capabilities.

Caution: If you are migrating from Django or Flask to FastAPI, note that FastAPI does not come with built-in components like an ORM (similar to Django’s) or a templating engine. Be prepared to integrate libraries like SQLAlchemy or Jinja2 for those functionalities.

Note: FastAPI’s auto-generated documentation supports both Swagger UI and ReDoc. These are especially useful for teams collaborating on API development as they provide an interactive interface for testing endpoints directly.

FAQ Q: Is FastAPI better than Django and Flask for all use cases? A: Not necessarily. While FastAPI is excellent for APIs and asynchronous programming, Django is better suited for full-stack applications, and Flask is ideal for lightweight, quick prototypes.

Q: Does FastAPI support databases out of the box? A: No, FastAPI doesn’t include a built-in ORM. However, you can easily integrate libraries like SQLAlchemy, Tortoise ORM, or GINO for database support.

Q: How does FastAPI handle validation errors? A: FastAPI uses Pydantic for validation and automatically generates detailed error messages for invalid data inputs, saving developers significant time.

Q: Can I use FastAPI for real-time features like WebSockets? A: Yes, FastAPI has built-in support for WebSockets, making it a great choice for real-time applications such as chat systems and live dashboards.

Q: What’s the best way to deploy FastAPI applications? A: FastAPI integrates well with Docker for containerization and Kubernetes for scaling. Use an ASGI server like Uvicorn or Daphne for production deployment.

Conclusion

FastAPI excels in modern, API-driven development, offering unparalleled performance, automatic documentation, and type safety. While Django and Flask still shine in specific scenarios, FastAPI is the future of Python APIs, designed for speed and scalability.

Ready to start? Install FastAPI today and see how it transforms your API development!

pip install fastapi uvicorn

Building MUNDRA: Revolutionizing MUN Delegate Management with Tech

Mon, 25 Nov 2024 21:06:26 +0000

When it comes to managing Model United Nations (MUN) events, the challenges are endless—keeping track of hundreds of delegates, streamlining communication, and planning large-scale events with precision. As the Joint General Secretary - Tech of the MUN Society MPSTME, I decided to tackle these challenges head-on.

That’s how MUNDRA – the MUNSoc Delegate Resource Application – was born. Named after the bustling Mundra Port in Gujarat, this backend application is designed to be the central hub for all delegate-related activities. More than just a database, MUNDRA is a scalable, secure, and modular solution that will power everything from our apps to email workflows and websites.

For developers and enthusiasts, MUNDRA's API is fully documented and accessible here, showcasing its well-structured design and functionality.

The Idea Behind MUNDRA

MUNs are as much about organization as they are about debate. Without a centralized system to manage delegate data, events can quickly devolve into chaos. MUNDRA was built to simplify this process by:

Centralizing all delegate and event data into a single database.
Automating repetitive tasks like account management and email verification.
Supporting scalable growth for larger MUN events in the future.
Offering seamless integration with websites, apps, and other tools.

As someone who loves creating meaningful tech solutions, this wasn’t just another project for me. It was about building a product that could evolve with our society’s needs.

Diving Into the Tech

MUNDRA is built on FastAPI, a modern Python framework known for its speed and simplicity. Here’s what makes MUNDRA stand out:

Key Features

Comprehensive User Management
- Delegate accounts with creation, deletion, and updates.
- Email verification ensures only genuine users have access.
- Hassle-free password recovery and change workflows.
Centralized Database
A unified storage system for delegate and event data, enabling easy retrieval and scalability for future growth.
Built-In Security
- Passwords are hashed using modern cryptographic standards.
- JWT-based authentication ensures secure access.
- Additional measures like rate limiting protect against abuse.
Integration Ready
MUNDRA is designed to plug into various tools—our app, event websites, and even automated email scripts.

Why FastAPI?

Choosing the right framework was critical to the success of MUNDRA. FastAPI emerged as the clear winner for its modern features:

Performance: It’s built for high-speed asynchronous processing.
Ease of Use: Automatic API documentation and intuitive type hints made development quick and error-free.
Scalability: FastAPI handles high-concurrency environments effortlessly.

You can explore the live API documentation here, powered by FastAPI's built-in OpenAPI support.

Building MUNDRA: Challenges and Lessons Learned

No journey is without its hurdles. Building MUNDRA taught me some valuable lessons:

Challenge: Scalability

MUN events grow larger every year. To ensure MUNDRA could keep up, I carefully designed the database schema and optimized API endpoints for handling large datasets.

Challenge: Security

Account workflows like password recovery are potential attack vectors. I implemented secure password hashing, email token validation, and rate limiting to safeguard user data.

Challenge: Modularity

MUNDRA had to be versatile enough to power apps, websites, and email scripts. I focused on designing clean, self-contained APIs that would work seamlessly across different front-end systems.

The Impact of MUNDRA

The first version of MUNDRA, v1.0.0, is already proving to be a game-changer for our society. With centralized data and automated workflows, we’ve saved countless hours of manual effort.

This backend isn’t just a tool; it’s a foundation for future innovation. Whether it’s real-time delegate tracking, analytics dashboards, or AI-driven insights, MUNDRA is built to evolve.

Beyond Code: What MUNDRA Means to Me

This project represents more than technical growth—it’s a testament to my ability to take an idea from concept to execution. As the Joint General Secretary - Tech, I didn’t just build a backend; I created a scalable product tailored to real-world needs.

MUNDRA reflects my passion for leveraging technology to solve problems at scale, and it’s something I’m incredibly proud of.

What’s Next?

MUNDRA is just getting started. Here’s a glimpse into the roadmap:

Real-Time Communication Tools: Instant updates for delegates.
Analytics Dashboards: Insights into delegate participation and event performance.
AI-Powered Tools: Recommendations for committee assignments and event planning.

Explore MUNDRA

Interested in the technical details or want to contribute?

Check out the source code on GitHub.
View the live API documentation at mundra.nnisarg.in/redoc.

Let’s build the future of MUN management together.

Coder Legion - Recent posts tagged fastapi

Building an ATS Resume Scorer API with FastAPI, Celery, and Docker

What it does

Tech stack

Design highlights

Source code

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

1. Understanding Multi-User Dashboards

2. Choosing the Technology Stack

React

FastAPI

PostgreSQL

SQLAlchemy

JWT and password hashing

Additional tools

3. Designing the Application Architecture

4. Designing the Database Schema

5. Implementing Authentication with FastAPI

Hashing passwords

Creating an authentication endpoint

6. Building the Authorization Layer

7. Implementing Role-Based Permissions

Avoiding permission escalation

8. Building the React Authentication Context

9. Protecting React Routes

10. Creating a Role-Aware Sidebar

11. Creating Different Dashboard Views

Administrator dashboard

Manager dashboard

Employee dashboard

12. Enforcing Data-Level Access Control

13. Building Dashboard APIs Efficiently

Pagination and filtering

Caching considerations

14. Handling Authentication and Session Security

Use short-lived access credentials

Protect browser storage

Configure CORS correctly

Validate every request

Prevent brute-force attacks

Protect privileged accounts

Use HTTPS

Avoid leaking sensitive information

15. Managing Role Changes and Permission Updates

16. Testing the Authorization Model

Testing with Pytest

17. Improving Dashboard Performance

Optimize database queries

Avoid unnecessary requests

Split large components

Use lazy loading

Paginate large datasets

Monitor real-world behavior

18. Improving the User Experience

19. Logging and Auditing Administrative Actions

20. Deploying the Application

21. Common Mistakes to Avoid

Trusting frontend roles

Giving every administrator unlimited access

Ignoring record ownership

Using one oversized API endpoint

Hard-coding role checks everywhere

Forgetting permission revocation

Skipping negative tests

Returning sensitive fields

22. A Practical Development Roadmap

Conclusion

How to Build a Lead Management Dashboard from Scratch

1. What Is a Lead Management Dashboard?

2. Define the Project Requirements

Essential features

Advanced features

3. Choose the Technology Stack

Frontend: React

Backend: FastAPI

Database: PostgreSQL

Additional tools

4. Design the Application Architecture

5. Plan the Database Schema

Leads table