Skip to main content

​
Core Principles

This monorepo follows a clean, scalable architecture designed for server-first development using Next.js App Router, TypeScript, XState, and Yup. It establishes standards for:
  • Separation of Concerns: Clearly delineating responsibilities across layers (UI, Actions, Machines, Services) following principles of Layered Architecture.
  • Microfrontend support: Enabling independent development and deployment of distinct business domain applications using a Microfrontend Architecture approach.
  • Code reuse: Maximizing code sharing across applications via centralized packages.
  • Server state orchestration: Utilizing typed XState machines (State Pattern) to manage complex server-side business processes, orchestrating calls to the Service Layer.
  • Structured Service Layer: Employing a domain-driven structure (Strategy Pattern, Factory Method/Service Locator) for defining service abstractions (interfaces, method DTOs) separately from concrete implementations, invoked by state machines.
For a detailed look at the core workflow, see the Core Workflow Guide. For specifics on backend implementation, see the Backend & Core Logic Guide. For frontend details, see the Frontend Development Guide. For Git standards, see the Git Convention Guide.

​
Monorepo Structure

The project is organized into apps (deployable units/microfrontends) and packages (shared code).
Project Root Structure
.
├── apps/
│   ├── web/                 # Shell or main UI application (optional)
│   ├── radicacion/          # Business domain app (e.g., Document Intake)
│   ├── asignacion/          # Another microfrontend (e.g., Case Assignment)
│   └── …                    # Other domain-specific applications
├── packages/
│   ├── core/                # Shared core business logic & foundational types
│   │   ├── actions/         # Server Actions (`'use server'`) - Validate input, start Machines
│   │   ├── machines/        # XState state machines - Orchestrate business logic, call Services
│   │   ├── services/        # Business/domain logic Service Layer - Implement specific operations
│   │   │   └── [domain]/    # e.g., 'user', 'radicacion'
│   │   │       ├── domain/  # Service Abstraction & Domain Types (Interface + DTOs)
│   │   │       │   ├── [Domain]Service.ts  # e.g., UserService.ts (Interface/Contract ONLY)
│   │   │       │   └── [Domain]Types.ts    # e.g., UserTypes.ts (Method Input/Output DTOs ONLY)
│   │   │       ├── implementations/        # Concrete Service Implementations (Strategy Pattern)
│   │   │       │   └── *.ts # e.g., DefaultUserService.ts, AdminUserService.ts
│   │   │       ├── serviceMap.ts # Resolves implementation (Factory Method/Service Locator)
│   │   │       └── index.ts      # Exports the service factory/locator function
│   │   ├── types/           # Shared BASE TypeScript types/interfaces (non-service specific)
│   │   │   ├── common/      # Truly generic types (e.g., PaginationResult)
│   │   │   ├── entities/    # Core data models/entities (e.g., User, Document)
│   │   │   │   ├── User.ts
│   │   │   │   └── Document.ts
│   │   │   │   └── ...
│   │   │   ├── machines/    # XState machine types (Context, Events), organized by machine/domain
│   │   │   │   ├── user/    # e.g., types for user machines
│   │   │   │   │   └── UserCreationMachineTypes.ts
│   │   │   │   ├── radicacion/ # e.g., types for radicacion machines
│   │   │   │   │   └── DocumentIntakeMachineTypes.ts
│   │   │   │   └── ...
│   │   │   └── index.ts     # Optional: Re-export key types for easier top-level imports
│   │   └── validation/      # Yup validation schemas - Used by Actions
│   ├── hooks/               # Shared React hooks (Cross-cutting concerns)
│   └── config/              # Shared configuration, env variables, feature flags
├── tsconfig.json            # Base TypeScript configuration (paths configured here)
├── turbo.json               # Turborepo configuration
└── package.json             # Root package manager file (pnpm workspace)
Note: UI components are provided by the external mappnext/ds-tw library, installed as a dependency.

​
Commands & Setup

Standard commands executed from the root of the monorepo:
Common Development Commands
# Install all dependencies for all apps & packages using pnpm workspaces
pnpm install

# Run development server for ALL apps concurrently using Turborepo
pnpm dev

# Build all apps and packages for production using Turborepo
pnpm build

# Run development server for a SPECIFIC app (e.g., radicacion)
# Replace 'radicacion' with the target app/package name
pnpm --filter radicacion dev

# Build only a SPECIFIC app/package and its dependencies
pnpm turbo build --filter=radicacion...

# Run tests across the monorepo (requires 'test' script in package.json)
pnpm test

# Lint the entire codebase (requires 'lint' script in package.json)
pnpm lint

​
Shared Package Roles (packages/)

Shared functionality is organized into dedicated packages. UI components come from an external library.
PackageDescriptionStandard Usage Example
@coreCentral hub for domain logic: actions, machines (State Pattern), services (following Strategy/Factory patterns with distinct domain/impl), core types (entities, common, machine), validation schemas.import { createUserAction } from '@core/actions';
@hooksReusable React hooks for cross-cutting concerns or complex UI logic.import { useFormValidation } from '@hooks/forms';
@configAccess to environment variables, runtime configuration, feature flags.import { isBetaFeatureEnabled } from '@config';
mappnext/ds-tw/*Mandatory UI Library (External). Provides all standard UI components.import { Button } from 'mappnext/ds-tw/atoms/Button';
Package aliases (@core, @hooks, @config) are configured in the root tsconfig.json under paths. These aliases must be used for importing shared code from packages/. UI components must be imported directly from mappnext/ds-tw/*.

​
Tech Stack

The core technologies mandated by this architecture:
ToolPurposeKey Location / Usage Area
Next.jsFull-stack React frameworkapps/* (App Router, Server Components, Server Actions)
TypeScriptStatic typingEntire codebase (.ts, .tsx)
XStateState machines & workflowspackages/core/machines/ (invoked by Actions, call Services)
YupSchema definition & validationpackages/core/validation/ (used by actions)
TurborepoMonorepo build system/orchestratorturbo.json, Root commands
pnpmEfficient package managerRoot package.json, workspaces
ReactFrontend UI libraryapps/*, packages/hooks
mappnext/ds-twStandard UI Component LibraryExternal Dependency, Imported in apps/*
TailwindCSSUtility-first CSS frameworkUsed by mappnext/ds-tw and potentially apps/*