Skip to main content

Wrkbelt Platform Architecture

This document provides a comprehensive overview of the Wrkbelt platform architecture, detailing all system components and their interactions. The architecture follows a modern microservices approach, implemented through an NX integrated monorepo structure.

System Landscape​

The following diagram illustrates the high-level architecture of the Wrkbelt platform:

Platform Components​

UI Layer​

The Wrkbelt platform's frontend is built using NextJS 15 with the App Router architecture, leveraging modern React 19 features and patterns.

Key Components:

  • NextJS Application: Provides both client-side and server-side rendering capabilities
  • NextJS Middleware: Handles cross-cutting concerns like authentication, localization, and feature flag integration
  • Server Components: Optimizes performance by rendering components on the server
  • Server Actions: Enables direct database interactions from client components

Technology Stack:

  • React 19
  • NextJS 15 (App Router)
  • ShadCN UI component library
  • Tailwind CSS 3
  • Redux (Redux Toolkit)

Hosting:

  • Deployed on AWS using SST and OpenNext
  • CloudFront for CDN and edge functionality
  • Lambda functions for server components and server-side rendering
  • S3 for static assets
  • Continuous deployment via GitHub Actions

API Layer​

The backend is built with NestJS following a three-layer architecture pattern for clear separation of concerns.

Architectural Layers:

  1. Controllers: Handle HTTP requests and define API endpoints
  2. Services: Implement business logic and orchestrate data operations
  3. Repositories: Provide data access abstraction for the database layer

Key Services:

  • Authentication: Uses Passport for authentication with support for multiple strategies
  • Redis Caching: Provides both session storage and general-purpose caching
  • Socket.io: Enables real-time communication between clients and server

Technology Stack:

  • NestJS framework
  • Mongoose ODM
  • MongoDB for data persistence
  • Redis for caching and session management
  • Express Session with Redis store

Hosting:

  • Deployed on AWS
  • Continuous deployment via GitHub Actions

Data Layer​

The data layer consists of two primary storage systems:

MongoDB:

  • Document-oriented NoSQL database
  • Used for primary data storage
  • Accessed via Mongoose ODM
  • Each entity extends from a base entity type defined in the shared types library

Redis:

  • In-memory data store
  • Used for:
    • Session management
    • Caching frequently accessed data
    • Supporting real-time features

Shared Libraries​

The Wrkbelt platform uses a set of shared libraries to promote code reuse and maintain consistency across the codebase:

Types Library:

  • Single source of truth for data types, DTOs, enums, etc.
  • Used by both UI and API layers
  • Defines base entity types extended by database models

Utils-Core-Logic:

  • Runtime-agnostic TypeScript logic
  • Can be used in both UI and API layers
  • Contains business logic for features like permission checking and media upload requirements

Utils-Primitives:

  • Contains foundational utility functions
  • Provides simple helpers like debounce, delay, and time formatting

I18n Library:

  • Internationalization support
  • Used across the platform for multi-language capabilities

Feature Flags Library:

  • Integration with Flagsmith
  • Enables feature toggles across the platform

Client Integration​

Scheduler Tool​

The Scheduler Tool is a key product offering that can be embedded in client websites:

Implementation:

  • Bundled JavaScript and CSS modules
  • Injected into client websites via HTML snippet
  • React-based implementation
  • Communicates with Wrkbelt API using API keys
  • Utilizes Socket.io for real-time updates

Supporting Systems​

Deployment Infrastructure​

GitHub Repository:

  • Central code repository for the NX monorepo
  • Source of truth for all platform code

CI/CD Pipeline:

  • GitHub Actions: Deploys API components to AWS
  • Netlify CI: Deploys UI applications

Environment Management:

  • Development, Staging, and Production environments
  • Environment variables stored in S3 buckets

External Service Integrations​

AWS Services:

  • S3: File storage for uploads and assets
  • SES: Email delivery service
  • KMS: Encryption and key management

Partner Services:

  • ServiceTitan: Integration for service businesses
  • Slack: Internal notifications and alerts (not customer-facing)
  • Hubspot: Internal CRM integration (not customer-facing)

Documentation and Testing​

Developer Documentation:

  • Internal documentation for engineers and stakeholders
  • Built with Docusaurus and hosted on Netlify

User Documentation:

  • Public-facing documentation for platform users
  • Built with Docusaurus and hosted on Netlify

Storybook:

  • Component library documentation and showcase
  • Features components from the UI components library
  • Used for development and demonstrations
  • Hosted on Netlify

Feature Flag Management​

Flagsmith:

  • Self-hosted on Railway
  • Provides feature flag management for the entire platform
  • Integrated with UI, API, and Scheduler components

Architectural Principles​

The Wrkbelt platform follows these core architectural principles:

  • SOLID: Single responsibility, Open-closed, Liskov substitution, Interface segregation, Dependency inversion
  • CLEAN Architecture: Clear separation of concerns and dependencies pointing inward
  • DRY (Don't Repeat Yourself): Code reuse through shared libraries and abstraction
  • KISS (Keep It Simple): Favoring simplicity and readability over complexity

Repository Structure & Organization​

The Wrkbelt platform is organized as an NX integrated monorepo, providing a modular approach to code organization and reuse. Here's a breakdown of the repository structure:

Top-Level Organization​

wrkbelt/
├── apps/            # Application packages
├── libs/            # Shared libraries
├── infra/           # Infrastructure code and tooling
├── tools/           # Development tooling and utilities
├── config/          # Configuration files
├── nx.json          # NX monorepo configuration
└── package.json     # Root package configuration

Applications (apps/)​

The apps directory contains the main applications that comprise the Wrkbelt platform:

  • api: NestJS backend application

    • Source code and business logic
    • Environment configuration
    • Docker configuration for containerization
    • Jest testing configuration

  • api-e2e: End-to-end tests for the API

  • ui: NextJS frontend application

    • NextJS 15 App Router implementation
    • Tailwind CSS configuration
    • Client-side state management
    • SST and OpenNext deployment on AWS

  • ui-e2e: End-to-end tests for the UI

  • dev-docs: Internal developer documentation (Docusaurus)

    • Technical documentation
    • API documentation
    • Architecture guides
    • Development guides

  • docs: Public user documentation (Docusaurus)

    • User guides and help documentation
    • Product documentation

  • cms: Content management system

Libraries (libs/)​

The libs directory follows a categorical organization to group related libraries:

API Libraries (libs/api/)​

  • config-api: Configuration libraries for the API

    • Environment configurations
    • Application settings

  • services-api: Core API services and modules

    • Authentication services
    • Data services
    • Business logic
    • Domain-specific implementations

  • templates-emails: Email templates

    • Handlebars templates
    • Email styling

  • utils-api: Utility functions specific to the API

    • Helper functions
    • Common patterns

  • utils-test-api: Testing utilities for API components

    • Test factories
    • Mocks and fixtures

Shared Libraries (libs/shared/)​

  • types-data: Data types and interfaces

    • Entity definitions
    • DTOs (Data Transfer Objects)
    • Enums and constants
    • Database schemas

  • types-platform: Platform-specific type definitions

  • utils-core-logic: Runtime-agnostic business logic

    • Permission checking
    • Validation rules
    • Shared algorithms

  • utils-primitives: Basic utility functions

    • String manipulation
    • Date formatting
    • Mathematical helpers

  • feature-flags: Feature flagging system integration

    • Flagsmith client configuration
    • Feature flag hooks and utilities

  • i18n: Internationalization resources

    • Translations
    • Localization utilities

  • utils-aws-cdk: AWS CDK utilities for infrastructure

    • Stack definitions
    • Resource helpers

UI Libraries (libs/ui/)​

  • ui-components: Reusable UI component library

    • ShadCN UI components
    • Custom components
    • Storybook configuration

  • brand: Brand assets and styling

    • Logos and icons
    • Color definitions
    • Typography

  • theme: Theming utilities

    • Theme definitions
    • Tailwind theme extensions

  • utils-next: NextJS-specific utilities

    • SSR helpers
    • NextJS middleware utilities
    • App Router utilities

Infrastructure (infra/)​

The infra directory contains infrastructure-related code and scripts:

  • src/ts: TypeScript infrastructure code

    • Helper functions
    • Deployment scripts
    • AWS CDK configuration

  • src/bash: Bash scripts for automation

  • local-dev: Local development environment setup

  • .env-vars: Environment variable templates and management

Tooling & Development Environment​

The Wrkbelt platform uses a variety of development tools to support the development workflow:

Build & Development Tools​

  • NX: Monorepo build system and task runner

    • Dependency graph management
    • Parallel task execution
    • Caching for faster builds

  • TypeScript: Typed JavaScript for all code

    • Strict type checking
    • Interface-driven development

  • ESLint: Code linting and style enforcement

  • Jest: Unit and integration testing

  • Cypress: End-to-end testing

Deployment & CI/CD​

  • GitHub Actions: CI/CD pipeline

    • Automated testing
    • Build and deployment of API services to AWS (Copilot)
    • Build and deployment of UI application to AWS (SST/OpenNext)

  • Netlify: Support application deployment platform

    • Deployment of dev-docs and Storybook
    • Preview deployments
    • Branch-based deployments
    • CDN and edge functions

  • Docker: Containerization for services

    • Consistent deployment environments
    • Local development parity

Development Experience​

  • Storybook: Component development and documentation

    • Component demos
    • Interactive documentation

  • Docusaurus: Documentation sites

    • Technical documentation
    • API documentation
    • User guides

Next Steps​