> ## 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.

# Quality & Conventions

> Mandatory naming conventions and the developer checklist for ensuring code quality and adherence to architectural standards.

## 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](./standards-backend))
* [ ] **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](./standards-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](./standards-workflow) & [Backend Guide](./standards-backend))
* [ ] **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](./standards-backend))
* [ ] **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.ts` and decoupled from validation/entity types? (See [Backend Guide](./standards-backend))
* [ ] **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](./standards-backend))
* [ ] **UI Library:** Are UI elements properly used from `mappnext/ds-tw`? (See [Frontend Guide](./standards-frontend))
* [ ] **Frontend Structure:** Are presentational components (`components/`) clearly separated from container logic (`page.tsx` or `containers/`) (**Container/Presentational Pattern**)? Is the chosen frontend structure appropriate for the complexity? (See [Frontend Guide](./standards-frontend))
* [ ] **Code Reuse:** Have shared packages (`@core`, `@hooks`, `@config`) been checked before writing new code? (See [Overview](./standards-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](./standards-git#git-commit-convention-standard) format?

<Warning>
  Pull Requests failing these checks may be rejected. Pay special attention to the correct Action -> Machine -> Service flow (including DTO mapping in the machine), commit message compliance, UI library usage, adherence to architectural patterns, and separation of concerns.
</Warning>

```
```