Active chapterCase study
Case study / 05
A fully modular e-commerce platform built as a Turborepo monorepo with a Fastify backend, Astro storefront (React islands), React + Vite admin panel, and three shared packages - featuring dynamic RBAC, convention-based route auto-registration, and background job processing.
01 / System behavior
A project-specific technical mechanism based on the recorded architecture and implementation context.
This monorepo confronts the scaling problem that emerges when a project outgrows a single-app architecture. It manages six inter-dependent packages with Turborepo's task graph and caching - a full rebuild that previously took 4+ minutes dropped to under 60 seconds after the first run populated the cache.
The Fastify backend uses Zod for compile-time type safety and runtime validation on every route. An autoRegisterRoutes utility scans the modules/ directory at startup and dynamically imports every *.route.ts file - adding a new module means creating the standard folder structure with zero manual imports or registration.
03 / Architecture record
A structured reading of the architecture recorded with this project.
The monorepo is structured into three applications and three shared packages:
Apps: • backend - Fastify API with modular route structure, Zod validation, JWT auth, and dynamic RBAC • frontend - Astro storefront with React islands for interactive components (cart, checkout) • admin - React + Vite admin panel for product, order, and user management
Packages: • @modular/ui - Shared UI component library with data-attribute theming • @modular/utils - Reusable utility functions across all apps • @modular/config - Centralized configuration including database connections and environment variables
The backend follows a strict modular convention: src/modules/<name>/controller, service, route, validator. Routes are auto-discovered and mounted at startup. Prisma handles database access with migrations and seeding.
The dynamic RBAC system auto-generates CRUD permissions for every Prisma model (product:create, product:read, etc.). Role-permission mappings live in the database, not in code - granting permissions is a database operation, no deployment needed. A Fastify preHandler decorator enforces permissions on every protected route.
The customer storefront is built with Astro, rendering static HTML by default and hydrating React islands only where interactivity is needed. Product listing pages are fully static (fast, cacheable, SEO-friendly), while the cart and checkout are hydrated React components.
05 / Selected highlights
The decisions and workflows that carry the most explanatory weight.
06 / Supported metrics
TypeScript, Turborepo, Fastify, Astro, React, Vite, Prisma, PostgreSQL, Redis, BullMQ, Zod, JWT
View source repository