STRPS Website Template

Date Published

STRPS Website Platform — Modern Monorepo Architecture & Strategic Refactor (In Progress)

Project Overview

The STRPS Website Platform is a production-grade, multilingual content-driven web ecosystem developed to support a professional services brand. The project began with a conventional PayloadCMS + Next.js template featuring tightly coupled backend and frontend layers. As requirements grew including planned e-commerce capabilities, live preview, and modular content blocks. The initial structure revealed clear limitations in scalability, maintainability, and independent iteration.

To address these challenges and establish a future-proof foundation, the architecture is being refactored toward a high-performance monorepo using Turborepo and pnpm workspaces. This approach aims to fully decouple concerns, significantly accelerate development velocity, enforce type safety across the stack, and create an extensible template suitable for enterprise-grade applications. While Turborepo orchestration is not yet fully implemented and the Medusa e-commerce components remain in an initial state, the foundational separation of the CMS backend and public frontend has been completed, providing a solid base for continued evolution.

Original Constraints & Motivation for Refactor

The legacy single-app structure imposed several limitations:

  • Tight coupling — Backend logic, admin UI, and public frontend shared the same build and deployment pipeline.
  • Slow feedback loops — Any change (content model, UI component, API) required rebuilding and testing the entire application.
  • Poor extensibility — Adding services such as headless e-commerce or third-party integrations increased complexity and risk.
  • Maintenance burden — Shared runtime environment complicated debugging and versioning.

These constraints drove a deliberate redesign focused on separation of concerns, independent deployability, and improved developer ergonomics, while fully leveraging Next.js performance capabilities.

Target Architecture — Monorepo Structure

The intended codebase organization adopts a Turborepo-powered monorepo with pnpm workspaces:

  • apps/
  • payload/                    PayloadCMS 3.x (Next.js App Router backend + admin panel)
  • frontend/                   Public website (Next.js 16, Apollo GraphQL, live preview)
  • medusa-store/               Medusa.js headless e-commerce engine (initial setup stage)
  • medusa-storefront/          E-commerce storefront (Next.js, integrated with Medusa; initial setup stage)
  • packages/
  • types/                      Shared TypeScript types generated from Payload schemas (@strps-website/types)
  • docs/                         Architecture decisions, conventions, onboarding guides

Core Architectural Principles (Designed & Partially Implemented)

  • Strict separation of concerns — Each major domain (CMS, marketing site, commerce) is intended to reside in its own isolated app.
  • Server Components first — Next.js App Router + React Server Components used by default for performance and security.
  • GraphQL as the universal query language — Apollo Client on the frontend provides efficient, type-safe data retrieval.
  • Single source of truth for types — Automatic type generation from Payload schemas, published to an internal package.
  • Incremental adoption of services — New domains (e.g., e-commerce via Medusa) are planned as independent apps with minimal cross-contamination.

Technology Choices & Rationale

  • Concern              Technology                               Primary Reason / Benefit
  • Framework            Next.js 16 (App Router)                  React Server Components, streaming, partial prerendering
  • Headless CMS         PayloadCMS 3.x + Lexical                 TypeScript-first, powerful access control, live preview
  • Monorepo tooling     Turborepo + pnpm workspaces              Fast caching, parallel execution, strict dependency management (implementation in progress)
  • Styling              Tailwind CSS 4 + shadcn/ui               Rapid prototyping, consistent design system, dark mode
  • Data fetching        Apollo Client (GraphQL)                  Normalized cache, subscriptions, excellent devtools
  • Database             PostgreSQL (Vercel Postgres in prod)     Relational integrity, horizontal scaling potential
  • Asset storage        Vercel Blob                              Zero-config, edge caching, cost-effective
  • Email delivery       Resend                                   Developer-friendly API, reliable deliverability
  • Animation            Motion (Framer Motion successor)         Smooth, declarative animations with gesture support
  • Icons                Lucide React                             Consistent, tree-shakeable icon set

Internationalization next-intl / built-in Next.js routing     Seamless support for en/es locales

Refactoring Progress — Key Milestones Achieved & Planned

  1. Extraction of PayloadCMS Completed: Admin panel and API routes migrated into a standalone Next.js app, preserving authentication and access control.
  2. Frontend decoupling & GraphQL adoption Completed: Replaced direct server actions / API routes with a typed GraphQL layer; live preview implemented using Payload’s official React integration.
  3. Monorepo foundation In progress: Turborepo pipelines, internal packages, and absolute imports (@/components, @/types, etc.) partially configured.
  4. Shared types automation Completed: Workflow established for payload generate:types → publish → consume, ensuring end-to-end type safety.
  5. Extensibility layer (Medusa integration) Initial stage: Medusa.js introduced as a planned independent service with its own storefront to demonstrate modularity.
  6. Developer experience hardening Ongoing: Conventions standardized for blocks/collections; hot-reload performance improvements and internal documentation in progress.

Measurable Outcomes (Achieved to Date)

  • Iteration speed — Frontend and backend development already decoupled, allowing parallel work without full-stack rebuilds.
  • Type safety — Generated types eliminate runtime type errors across the frontend ↔ CMS boundary.
  • Maintainability — Clear separation reduces cognitive load and supports faster onboarding.
  • Production readiness — Core CMS + frontend stack deployed to Vercel with preview/production environments.

Conclusion

The ongoing refactor of the STRPS platform applies modern full-stack best practices—including monorepo organization, headless architecture, type-safe data layers, and performance-first rendering—with the goal of creating a scalable foundation for a live brand website and a reusable blueprint for future content-heavy, service-oriented projects.

This work demonstrates advanced proficiency in system design, large-scale TypeScript usage, Next.js optimization patterns, and pragmatic adoption of emerging tools (Payload 3.x, Turborepo, Tailwind 4, Medusa.js, etc.). The completed decoupling phases already deliver tangible improvements, while the remaining Turborepo refinement and Medusa integration represent natural next steps toward full modularity and extensibility.

For implementation details, code conventions, and lessons learned to date, refer to the docs/ directory in the repository.

(repository available on request under NDA)