Skip to main content
zilara · architecture
Zilara: Headless Multi-Tenant E-Commerce Platform Architecture — Architecture and Implementation Showcase

01 · Executive Overview

Zilara is a decoupled headless e-commerce architecture designed to deliver fast product catalog navigation, no platform transaction fees, and complete database sovereignty. The system combines an asynchronous Medusa.js v2 Node.js backend with an optimized Zoneless Angular Server-Side Rendered (SSR) storefront.

02 · The Problem & Engineering Constraints

Monolithic e-commerce platforms (such as Shopify and Magento) impose escalating per-transaction fees, rigid plugin ecosystems, and bloated client runtimes that degrade Core Web Vitals (INP, LCP). Businesses requiring multi-currency support, custom checkout workflows, and specialized inventory logic suffer from high operational costs and slow page hydration.

03 · Measurable Engineering Impact

0%

Platform Transaction Fee

Full Revenue & Data Sovereignty

Optimized FCP

First Contentful Paint

Isomorphic SSR Pre-Rendering

Typed request/response contracts

Typed Contract Coverage

End-to-End TypeScript Validation

04 · Technical Solution & Strategy

Architected a decoupled headless system separating transactional business logic from presentation. Implemented a Medusa.js v2 Node.js backend managing product catalogs, cart state, order workflows, and payment integrations against PostgreSQL. Built a Zoneless Angular SSR frontend styled with Tailwind CSS, utilizing Server-Side Rendering for early First Contentful Paint and search crawler indexing.

Medusa.js v2 Architecture

Decoupled headless commerce backend providing extensible order workflows and zero platform tax.

Zoneless SSR Storefront

Pre-rendered HTML structures optimizing First Contentful Paint and guaranteeing full crawlability.

Containerized CI/CD Pipeline

Dockerized microservice environment deployed on self-hosted Linux VPS via Coolify automation.

05 · Role & Core Contributions

Architected the headless system topology, RESTful API contracts, and PostgreSQL relational schema design.

Developed the Zoneless Angular SSR storefront with Angular Signals to eliminate Zone.js hydration latency.

Configured Medusa.js v2 workflow subscribers for transactional webhooks and inventory synchronization.

Orchestrated multi-container Docker deployment pipelines managed via Coolify on a Linux VPS node.

06 · System Architecture & Subsystems

The architecture comprises an Angular SSR presentation layer communicating over typed REST APIs with a decoupled Medusa.js v2 micro-service core. PostgreSQL handles transactional relational persistence while Redis manages transient cart caching and asynchronous task queuing.

Zoneless Angular SSR Storefront

Client & Crawler Presentation Layer

Server-Side Rendered Angular frontend generating static HTML for optimal First Contentful Paint (FCP) and seamless hydration.

Pre-rendered HTML for search engine discoverability
Optimized initial page load times
Zero cumulative layout shift (CLS < 0.01)
Optimistic UI state for cart and checkout flows
Angular (Zoneless) Angular SSR Express Engine Tailwind CSS Signals

Medusa.js v2 Headless Commerce Engine

Transactional Backend & Order Workflow

Decoupled Node.js commerce core handling catalog management, customer authentication, tax calculations, and payment webhooks.

Extensible order lifecycle workflows
Multi-currency and localized pricing support
Role-based merchant admin capabilities
Zero platform percentage fees on transactions
Medusa.js v2 Node.js TypeScript PostgreSQL 16 Redis

Containerized Infrastructure & Cache

Persistence, Caching & Deployment

Isolated Docker environment running PostgreSQL 16, Redis caching, and automated Coolify continuous delivery pipelines.

Automated SSL provisioning and zero-downtime container updates
Redis-backed session and cart state caching
Automated daily PostgreSQL snapshot backups
Docker PostgreSQL Redis Coolify Linux VPS Nginx

07 · Key Technical Decisions & Tradeoffs

Decoupled Medusa.js v2 Architecture vs Monolithic SaaS

Rationale

Guarantees complete database ownership, zero recurring platform percentage fees, and unrestricted custom backend workflow logic.

Tradeoff & Mitigation

Requires dedicated self-hosted DevOps maintenance (database replication, Redis caching, security patching).

Angular SSR with Zoneless Signals over Client-Only SPA

Rationale

Ensures HTML pre-rendering for search engine crawlers and delivers fast initial render on mobile networks.

Tradeoff & Mitigation

Increases server compute requirements during high-concurrency traffic bursts, requiring reverse proxy caching.

Redis-Backed Transient Cart State with Optimistic UI

Rationale

Eliminates database write contention on rapid cart quantity updates through Redis caching.

Tradeoff & Mitigation

Requires multi-tab synchronization logic to resolve race conditions across active browser windows.

08 · Deployment & Production Infrastructure

Deployed as an orchestrated multi-container Docker cluster (SSR Storefront, Medusa.js API, PostgreSQL 16, Redis) on a Linux VPS managed via Coolify. Traffic is routed through Nginx with TLS 1.3 termination and Cloudflare CDN caching.

09 · Comprehensive Stack Architecture

Frontend & SSR Layer

Angular (Zoneless) Signals Angular SSR / Express Tailwind CSS

Commerce Core & API

Medusa.js v2 Node.js TypeScript RESTful API Webhooks

Persistence & Caching

PostgreSQL 16 Redis Connection Pooling

DevOps & Orchestration

Docker Compose Coolify Linux VPS Nginx Cloudflare CDN
Direct Line: WhatsApp