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.
Naming Conventions
Strict adherence to these naming conventions is required for code consistency and predictability across the monorepo.| Artifact Type | Suffix/Prefix Convention | Example | Standard Location Example |
|---|---|---|---|
| Yup Schema | Schema suffix | userSchema | packages/core/validation/userSchema.ts |
| Schema Type (Input) | Input suffix | CreateUserInput | packages/core/validation/userSchema.ts |
| Base Entity Type | Noun (Singular) | User | packages/core/types/entities/User.ts |
| XState Machine | Machine suffix | userCreationMachine | packages/core/machines/userCreationMachine.ts |
| Machine Context Type | MachineContext suffix | UserCreationMachineContext | packages/core/types/machines/user/UserCreationMachineTypes.ts |
| Machine Event Type | MachineEvent suffix | UserCreationMachineEvent | packages/core/types/machines/user/UserCreationMachineTypes.ts |
| Service Interface | Service suffix | UserService | packages/core/services/user/domain/UserService.ts |
| Service Impl Class | [ImplName]Service suffix | DefaultUserService | packages/core/services/user/implementations/DefaultUserService.ts |
| Service Method DTOs | [MethodName]Input/Output | CreateUserMethodInput | packages/core/services/user/domain/UserTypes.ts |
| Server Action | Action suffix | createUserAction | packages/core/actions/userActions.ts |
| Container Comp. | Container suffix | UserFormContainer.tsx | apps/[appName]/app/.../containers/ |
| Page Component | page.tsx (exact name) | page.tsx | apps/[appName]/app/.../[pageName]/page.tsx |
Developer Checklist
Before submitting a Pull Request for review, developers must verify the following:- Input Validation: Is input data validated using a shared Yup schema (
@core/validation) within the Server Action before starting the machine? (See Backend Guide) - Action Logic: Does the Server Action instantiate the correct XState machine (
@core/machines), pass validated input and resolved service to context, send the initial event, and await its completion? (See Core Workflow) - Machine Orchestration: Does the XState machine orchestrate the business logic flow?
- Machine-Service DTO Mapping: Does the XState machine correctly construct the Service Input DTO before calling the service method? Does it correctly process the Service Output DTO and update its context? (See Core Workflow & Backend Guide)
- Service Invocation: Does the XState machine invoke methods on appropriate Service implementations (
@core/services/[domain]/implementations/) obtained via context? - Service Resolution: Is the correct service implementation resolved (via Factory/Locator) and made available to the machine (e.g., via context)? (See Backend Guide)
- State Modeling: Are complex stateful workflows correctly modeled within the XState machine (
State Pattern)? - Service Logic: Are discrete business operations implemented within Service classes (Strategy Pattern)?
- Service Contracts: Are Service Interfaces defined in
@core/services/[domain]/domain/[Domain]Service.ts? Are specific Service Method Input/Output DTOs defined in@core/services/[domain]/domain/[Domain]Types.tsand decoupled from validation/entity types? (See Backend Guide) - Typing: Are XState machine Context/Event types defined in
@core/types/machines/[domain]/? Are base entity types defined in@core/types/entities/? (See Backend Guide) - UI Library: Are UI elements properly used from
mappnext/ds-tw? (See Frontend Guide) - Frontend Structure: Are presentational components (
components/) clearly separated from container logic (page.tsxorcontainers/) (Container/Presentational Pattern)? Is the chosen frontend structure appropriate for the complexity? (See Frontend Guide) - Code Reuse: Have shared packages (
@core,@hooks,@config) been checked before writing new code? (See Overview) - Build: Does the project build successfully (
pnpm build)? - Documentation: Are docs/comments updated where necessary (explaining complex ‘why’, not ‘what’)?
- Commits: Do all commits follow the Conventional Commits format?