Overview & Setup

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.

Package	Description	Standard Usage Example
`@core`	Central 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';`
`@hooks`	Reusable React hooks for cross-cutting concerns or complex UI logic.	`import { useFormValidation } from '@hooks/forms';`
`@config`	Access 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:

Tool	Purpose	Key Location / Usage Area
Next.js	Full-stack React framework	`apps/*` (App Router, Server Components, Server Actions)
TypeScript	Static typing	Entire codebase (`.ts`, `.tsx`)
XState	State machines & workflows	`packages/core/machines/` (invoked by Actions, call Services)
Yup	Schema definition & validation	`packages/core/validation/` (used by actions)
Turborepo	Monorepo build system/orchestrator	`turbo.json`, Root commands
pnpm	Efficient package manager	Root `package.json`, workspaces
React	Frontend UI library	`apps/*`, `packages/hooks`
`mappnext/ds-tw`	Standard UI Component Library	External Dependency, Imported in `apps/*`
TailwindCSS	Utility-first CSS framework	Used by `mappnext/ds-tw` and potentially `apps/*`

Guides & Best Practices

MappTech Standards

Articles & Talks

Tutorials & Guides

Core Principles

Monorepo Structure

Commands & Setup

Shared Package Roles (`packages/`)

Tech Stack

​Core Principles

​Monorepo Structure

​Commands & Setup

​Shared Package Roles (packages/)

​Tech Stack

Core Principles

Monorepo Structure

Commands & Setup

Shared Package Roles (`packages/`)

Tech Stack