> ## Documentation Index > Fetch the complete documentation index at: https://blog.mapptech.com.co/llms.txt > Use this file to discover all available pages before exploring further. # Overview & Setup > Introduction to the MappTech server-first monorepo architecture, core principles, structure, technology stack, and essential setup commands. ## 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](./standards-workflow).* *For specifics on backend implementation, see the [Backend & Core Logic Guide](./standards-backend).* *For frontend details, see the [Frontend Development Guide](./standards-frontend).* *For Git standards, see the [Git Convention Guide](./standards-git).* *** ## Monorepo Structure The project is organized into `apps` (deployable units/microfrontends) and `packages` (shared code). ```text Project Root Structure theme={null} . ├── 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: ```bash Common Development Commands theme={null} # 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/*` | ``` ```