Designing and Implementing DevGuard: Architecture, Security Decisions, and Engineering Lessons

DevGuard started as a simple idea in my mind: to build a reusable, secure, developer-friendly authentication system that could save me and other developers from rewriting the same authentication logic repeatedly. What it became was a technical journey filled with architectural decisions, real-world challenges, and hands-on learning about backend systems, security, and deployment constraints.

In this article, I want to share how I designed and built DevGuard, the trade-offs I made, the technical problems I solved, and the skills I gained. I also want to explain why the project is currently on hold.

Why I Built DevGuard

Almost every modern application requires authentication and user management. But in practice, I noticed that building authentication from scratch every time leads to issues like;

• Security gaps
• Mix authentication and business logic
• Re-implementing the same features repeatedly
• Difficulty in maintaining and scaling

I built DevGuard to provide a clean, reusable, API-first authentication core that works for both web and mobile clients, enforces secure defaults, and can be integrated into any backend.

I also had clear constraints while building it:

• Stateless APIs that don’t rely on server-side sessions
• Support for web and mobile clients
• Secure-by-default patterns to prevent common mistakes
• Backend-only focus (no UI)
• Limited infrastructure resources

These constraints shaped every decision I made.

System Overview

I implemented DevGuard as a modular monolithic backend, one service with clear internal separation rather than multiple microservices.

Core Components

• Auth Module: Handles login, registration, token creation, and refresh
• User Module: Manages user persistence, roles, and profile data
• Security Layer: Handles password hashing, token signing, and verification
• Middleware Layer: Protects routes and enforces authorization
• Configuration Layer: Handles environment-safe secrets and runtime settings

Technology Stack

• Backend: Node.js + Express
• Language: TypeScript
• Database: PostgreSQL
• Authentication: JWT (Access + Refresh tokens)
• Password security: bcrypt
• Deployment: Docker

This structure made DevGuard easy to test, maintain, and extend, while keeping it simple to deploy.

Key Technical Decisions and Trade-Offs

Architecture: Modular Monolith

I chose a modular monolith over microservices because it:

• Reduced operational complexity
• Made testing and debugging easier
• Avoided premature decomposition

The trade-off is that modules cannot scale independently without refactoring later. For DevGuard’s initial scope, simplicity and clarity were more important.

Authentication Strategy: JWT

I implemented JWT-based stateless authentication. This means the server does not store session data; instead, tokens carry identity and permission information securely.

Implementation details:

• Short-lived access tokens for regular requests
• Refresh tokens for renewing access without logging in again
• Centralized verification middleware for protected routes

This strategy works across web and mobile apps and supports horizontal scaling. The trade-off is that it requires careful token lifecycle handling and client coordination.

Password Security

Passwords are never stored in plain text. I used bcrypt with configurable salt rounds for its proven security against brute-force attacks.

I kept all password logic in a dedicated security service, so it never leaked into controllers or business logic. This separation helped reduce risk and improved code clarity.

Authorization Model: RBAC

I implemented Role-Based Access Control (RBAC). Users have defined roles, and middleware enforces access permissions before the business logic executes.

This approach:

• Keeps authorization separate from functional code
• Makes access rules predictable
• Simplifies maintenance as the system grows

Core Data Models and API Design

I designed DevGuard with clear models and predictable APIs to make it easy to integrate.

Key Entity: User

Fields include:

• id
• email
• password_hash
• role
• status

API Design Principles

• RESTful naming conventions
• Stateless requests
• Consistent error responses
• Explicit HTTP status codes

Example Endpoints:

• POST /auth/register
• POST /auth/login
• POST /auth/refresh
• GET /users/me

These choices make the API predictable and easy to adopt for client applications.

Technical Challenges and Solutions

Token Refresh Failures on Unstable Networks

Problem: Access tokens expired mid-interaction, causing unexpected logouts.

Cause: Refresh logic was too closely tied to individual requests.

Solution:

• Centralized token expiry handling
• Implemented refresh token rotation
• Defined clear retry rules for authorization failures

Result: More stable authentication flows, especially on mobile networks.

Deployment and Infrastructure Limitations

Problem: I couldn’t fully deploy DevGuard to the cloud due to limited credits, regional restrictions, and cost barriers. One thing that is most common for Africans is a lack of resources; no student credit cards to create accounts.

Solution:

• Containerized the application with Docker
• Reduced reliance on provider-specific services
• Made it deployable locally or on self-hosted infrastructure

Result: DevGuard is portable and ready for production, but full cloud deployment isn’t feasible with my current resources, which is why the project is paused.

What I Would Improve or Redesign

If I had more time or resources, I would:

• Integrate OAuth providers like Google and GitHub
• Implement token revocation lists for better session management
• Add rate limiting and audit logging
• Expand RBAC to fine-grained permissions
• Consider GraphQL or aggregated endpoints to reduce API calls

These are deliberate improvements, not accidental oversights.

Skills and Technical Capabilities I Gained

Working on DevGuard helped me strengthen several backend engineering skills:

System Design & Architecture

• Designing modular backend systems
• Defining clear service boundaries
• Making architecture trade-offs under constraints

Authentication & Security

• Implementing stateless JWT authentication
• Designing secure token lifecycles
• Handling password hashing and credential protection
• Writing authorization middleware

Backend Engineering

• REST API design and versioning
• Error handling and HTTP semantics
• Environment-based configuration and secrets management
• Writing reusable, testable backend modules

Infrastructure & Deployment

• Docker-based application packaging
• Handling portability challenges
• Designing systems resilient to infrastructure limitations

Engineering Judgment

• Avoiding premature optimization
• Managing technical debt consciously
• Evaluating trade-offs between correctness, scalability, and resources

These skills are directly transferable to real-world backend and platform engineering roles.

Conclusion

DevGuard reaffirmed a critical lesson for me: building authentication systems is fundamentally about architecture and security, not just frameworks or libraries.

I was able to:

• Build a reusable authentication core
• Apply secure-by-default design patterns
• Maintain clean separation of concerns
• Understand the limits imposed by infrastructure constraints

While DevGuard is paused due to resource limitations, the work accomplished stands as a technical reference and learning artifact, and I hope it can inspire other developers working on similar projects in resource-constrained environments. Here is an article that also talks extensively on my documenting challenges when building DevGuard https://www.garudax.id/pulse/building-devguard-journey-learning-failing-overcoming-eileen-leila-q3jkf/?trackingId=tc%2B8CKRdcrjCs6sK070fuQ%3D%3D