Building a Modular Architecture with Microservices, Microfrontends, and a Local Shell App

canonical_url: https://medium.com/@albe.mtz/building-a-modular-architecture-with-microservices-microfrontends-and-a-local-shell-app-9cf2d99e5773

Originally published in Medium: link

Introduction

In a cloud-dominated era, modern infrastructure solutions often rely on external services, centralized configurations, and tightly coupled ecosystems. However, not every development environment benefits from or requires that dependency.

This article explores a modular, autonomous, and locally hosted alternative based on a Shell App that orchestrates microservices and microfrontends within a private network.

This approach is ideal for developers seeking a fully functional, offline-ready environment—perfect for labs, controlled testing, and low-cost deployments using mini PCs or home servers.

What is a Shell App and How Does It Work?

The Shell App is a containerized application acting as the backbone of the system. It integrates various frontend and backend modules while acting as a single point of entry for both users and internal services.

1. Route Management

The Shell App detects available modules via a central database or dynamic config file, then uses reverse proxy logic to route incoming requests to their respective services. This allows a single domain (e.g., app.local) to dynamically serve content from multiple internal modules.

Routing is powered by http-proxy-middleware, enabling clean delegation of paths like /api/users or /dashboard to containers without directly exposing their ports.

2. JWT Authentication

It handles all incoming JWT tokens, verifying:

• Signature validity
• Token expiration
• Role or permission claims

On login, the Shell App issues the token to the frontend, ensuring secure, stateless sessions.

3. Serving Microfrontends

Instead of a monolithic UI, the Shell App dynamically loads microfrontends based on active modules. This is achieved via:

• Dynamic JS imports from sibling containers
• Webpack Module Federation (or similar alternatives)

The Shell App injects these microfrontends into a shared UI shell, allowing the UI to scale independently with backend capabilities.

4. Module Registry via Central Database

The Shell App queries a local database (PostgreSQL or SQLite) to check which modules are active, their ports, routes, and capabilities. This registry enables:

• Dynamic route mapping
• Error handling for inactive services
• Status dashboards for module availability

The registry can be maintained manually, via service discovery scripts, or using container metadata.

General Architecture

The architecture consists of loosely coupled, containerized services communicating over an internal network:

🧠 CORE Shell App

The orchestrator for all routes, UIs, and security. It’s the access gateway, API proxy, and dynamic loader of all frontend content.

🎨 Microfrontends

Each module has its own independently built UI. These are loaded on-demand into the Shell App, ensuring teams can work in isolation and update without affecting others.

⚙️ Microservices (Backends)

Each functional area (e.g., users, metrics, auth) is handled by a dedicated service, often with its own language, database, and API interface. They connect through well-defined HTTP routes proxied by the Shell App.

🗄️ Central Database

Maintains system-wide configuration: active modules, routes, status, and shared resources like tokens or user roles.

📦 Docker Containers

Each part of the system—frontends, backends, databases—is isolated in its own container. Networking is managed via Docker or K3s, and modules only expose necessary ports internally.

Use Case: Local Network Deployment

This system is deployed on a physical Linux machine (such as a mini PC), running docker compose or k3s (lightweight Kubernetes).

The Shell App exposes HTTPS using self-signed certificates and can be accessed from any local device using internal DNS names like dashboard.local or auth.local.

This brings major benefits:

• Full control over the environment and data
• No reliance on public cloud
• Low hardware requirements
• Perfect for test environments, offline labs, or secure dev spaces

Benefits and Limitations

✅ Advantages

• Real modularity: plug-and-play services
• Easy local scaling and maintenance
• Secure and offline-capable by design

⚠️ Limitations

• Requires Docker/Kubernetes knowledge
• Setup can be complex without a GUI
• Not optimized for public deployment without hardened security

Conclusion

This architecture proves it’s entirely possible to create a modern, modular, and functional DevOps environment without the cloud.

Using standard tools like Docker, Kubernetes, and TLS, you can build a complete platform ready for testing, development, or private deployment.

Coming next: we'll explore automating this environment with Terraform and Dev Containers, as well as integration with tools like Grafana, Portainer, and distributed databases.