@battle-racing/br-common-lib/docs/MIGRATION_GUIDE.md

Common library for all Battle Racing Repositorios

# Hardware Domain Migration Guide

This document serves as a step-by-step cleaning and refactoring guide for an AI Model to migrate legacy hardware types to the new `src/domains` structure.

We are migrating from `src/types` to `src/domains`.
We will keep the old types in `src/types` for now, but we will remove them in the next major release. (don't change anything on the /types folder).

## 1. Architecture Principles

For each component (e.g., `Lights`, `Sound`, `Race`), we must create a dedicated directory in `src/domains/hardware/[component-name]` with 4 files:

1.  **`[ComponentName].const.ts`**:
    - Contains all constants (Status, Commands, Configuration options).
    - Use `as const` assertions.
    - **NO** TypeScript `enum`. Use objects.
    - Example: `LIGHTS_STATUS`, `LIGHTS_ACTION_COMMAND`.

2.  **`[ComponentName].schema.ts`**:
    - Depends on `[ComponentName].const.ts`.
    - Contains Zod schemas.
    - Use `z.enum(CONSTANT)` for string unions.
    - Example: `lightsStatusSchema`, `lightsConfigurationSchema`.

3.  **`[ComponentName].types.ts`**:
    - Depends on `[ComponentName].schema.ts`.
    - Contains **inferred** TypeScript types using `z.infer<>`.
    - **DO NOT** manually define interfaces if a schema exists.
    - Example: `export type LightsStatus = z.infer<typeof lightsStatusSchema>;`.

4.  **`index.ts`**:
    - Exports everything from the above 3 files.
    - Some domains could have more than one Entity, but they are, so we should export all of them.

you need to be sure in the index.ts you're exporting domains, and not types, otherwise you'll get errors of duplicate Types.

## 2. Migration Checklist

Double check the existing types and verify the new ones on `domains` are compatible.

Create a migration plan, and don't change anything on the /types folder son we can compare the new ones are correct.

## 3. Clean Up & wiring

- [ ] Update `src/domains/hardware/index.ts` to export new modules.
- [ ] Remove duplicate constants in `src/constants/`.

## 4. Verification

- [ ] Run `npm run build` to ensure no type errors.
- [ ] Check for circular dependencies.