High Level Solution Design HLD - Designing a Modular Microservices Architecture



Overview

This architecture powers a scalable ecosystem of microservices behind a unified API Gateway. It is built with flexibility in mind, allowing new services—like notifications, analytics, or billing—to be added without disrupting existing flows.

Principles

Microservices by Function: Each service has a clear boundary (auth, logging, parsing, etc.). That’s the right granularity.

Identity as Core AuthZ/AuthN: All auth flows centralize through identity-backend, which is best practice and sets you up for RBAC, SSO, etc. later.

Service-to-Service Auth MVP: You’ve implemented service-to-service auth (machine identity) first, which is usually the most vulnerable point in a microservice mesh

JWT for User Auth: Issuing JWTs for users is scalable and stateless—works well for API-first architecture and you can layer on claims/roles later.

Core Components

1. API Gateway

  • Single entry point for web and mobile clients.

  • Handles routing, authentication, and throttling before requests reach internal services.

  • Simplifies external integration: clients don’t need to know individual service URLs.

2. Identity Backend

  • Serves as the trust anchor for the entire platform.

  • Responsibilities:

    • Issues and verifies JWT tokens for service-to-service and user-to-service authentication.

    • Centralizes key management (e.g., rotating secrets).

    • Ensures consistent claims across all microservices (issuer, audience, subject).

3. Logging Backend

  • Collects application logs from all services.

  • Supports:

    • Centralized troubleshooting (view logs in one place).

    • Audit trails for compliance and monitoring.

    • Scalable storage: can switch from SQLite (MVP) to Postgres/Elasticsearch as traffic grows.

4. Notification Backend

  • Event-driven for real-time notifications.

  • Handles asynchronous communications to users:

    • Email, SMS, or push notifications.

  • Decoupled from core flows:

    • Services like logging or identity can publish events (e.g., “new user registered”) without knowing notification logic.

  • Future-ready for pub/sub or event streaming.

  • As traffic grows or jobs become compute-heavy, spin off a batch service:

    Move scheduled/compute-heavy workflows there.

    Keep Notification strictly for delivery.

Data Stores

  • Each service owns its own database:

    • Promotes loose coupling (schema changes don’t affect others).

    • Enables polyglot persistence (e.g., Postgres for identity, Elasticsearch for logs).

Scalability and Modularity

  • Independent scaling: Heavy logging traffic can scale logging-backend without touching identity or notifications.

  • Rolling upgrades: Deploy new features or fixes to one service without downtime across the platform.

  • Easy onboarding of new services: New microservices (e.g., analytics-backend) simply integrate with the gateway and identity for auth.

Security

  • Centralized authentication via JWT:

    • Each service trusts tokens issued by identity-backend.

    • Secrets validated through /debug-env endpoints during debugging.

  • Future roadmap:

    • Support for multiple signing keys (per client or per environment).

    • Role-based claims (e.g., service roles vs user roles).

Why This Approach Works

  • Flexibility: Add or remove services without breaking clients.

  • Isolation: Bugs in one service (e.g., notifications) don’t cascade to others.

  • Evolution-ready: Start with minimal services; grow toward event-driven architecture or Kubernetes orchestration later.

Example: Adding Notification Service

  • Trigger: A user signs up via the web client.

  • Flow:

    1. Web client calls API Gateway → Identity issues token.

    2. User profile service creates account → publishes “user_created” event.

    3. Notification service subscribes to this event → sends welcome email/SMS.

  • Result: Decoupled communication—no direct dependency between profile and notification logic.


Comments

Post a Comment

Popular posts from this blog

Feature: Audit log for one login, and identity service

Image
Customer (Product) Page High-Level System Design Diagram (PlantUML) Sequence Diagram: Audit Event Ingestion Sequence Diagram: Orchestration Event For a High-Level System (Component) Diagram The queue is implemented as message_queue (generic), and the audit log service consumes from it, writing to a dedicated audit_log table. The logging service also consumes from the same message_queue and writes to log_store. Orchestration/other services use the same queue. Summary Table: What Writes Where Event Type Goes Into Consumed By Final Storage audit message_queue Audit Log Service audit_log table log message_queue Logging Service log_store table doc_uploaded message_queue Orchestration Worker (business DB, or triggers next event) ocr_ready message_queue Notification Worker, etc. (notification log, etc.)  Core Tables message_queue – universal event bus (temp buffer) audit_log – immutable audit/compliance events log_store – application logs (op...
Read more

Getting started - Build your data science lab environment

This guide explains how to set up a complete data science environment for the udemy program. A proper setup ensures compatibility and avoids recurring environment issues.  1. Overview Goal : Create a full-featured environment with sufficient resources for all course exercises. Recommendation : Use Anaconda for the most reliable setup. Alternative : Use a Python virtual environment with pip if Anaconda isn’t working. 2. Setup Options Primary (Recommended) Create a dedicated Anaconda environment (isolated, compatible). Alternative Use a standard Python virtualenv + pip (faster but less reliable). 3. Windows Setup Steps Clone Course Repository git clone https://github.com/ed-donner/llm_engineering/ Follow the repository’s README.md instructions for additional setup details. Create Anaconda Environment Inside the llm_engineering folder: conda env create -f environment.yml ⏳ This may take several minutes. Activate the environment: conda activate llms Deactivat...
Read more

QA - Run #1 - Results

Image
# QA Report for Tag QA_July2025_A - **Tag/Commit:** QA_July2025_A (`f32abc1`) - **Date:** 2025-08-01 - **QA Outcomes:** All tests passed except for file upload (see below)... - **Environment:** Windows 10, Python 3.12, requirements.txt as of tag - **Notes:** See log for detailed results. ## Issue Found - **Step:** - **Bug:** - **Log excerpt:** - **Screenshot:** For this QA run, we begin with pristine state by: Stop all services Delete logs.db, and jobs.db Delete all files in doc_store folder Start all services Test, you should see no data on index page, and query should result in no data found error Next, go ahead and upload new1.txt, and after that new2.txt Issue the query: "can you summarize all of the todo items you can find, seperating each one on a single line, with due date first, then title, and description with any details you can augment" Expected Answer: - August 1, 2025: Respond to Amira and discuss weekend plans - August 3, 2025: Go to Somesh class and finish ta...
Read more