react-architecture

This skill defines the standard approach for scaffolding a complete frontend entity architecture in this project. It creates all necessary files following the established patterns: Types, Service, Context, Hook, and Provider registration.

Prerequisites

Before creating the architecture, you MUST:

1. Ask the user for the entity name (e.g., "Clan", "Achievement", "Shop")
2. Ask the user for the API base path (e.g., "/api/clan", "/api/achievement")
3. Ask the user for the entity fields/properties or check if API documentation exists in docs/
4. Check if the entity already exists — search src/types/, src/services/, src/contexts/, and src/hooks/ before creating anything

Creation Order

Always create files in this exact order:

1. Types → src/types/{entity}.ts
2. Service → src/services/{entity}Service.ts
3. Context → src/contexts/{Entity}Context.tsx
4. Hook → src/hooks/use{Entity}.ts
5. Provider registration → src/main.tsx

Rules

1. Never use any type — all types must be explicitly defined.
2. Never use alert() or window.confirm() — use toast from sonner for notifications and ConfirmModal for confirmation dialogs.
3. Always use useCallback for all context methods to prevent unnecessary re-renders.
4. Always include loading, error, and main data state in every context.
5. Always use the class-based service pattern with private handleResponse method.
6. Always use getHeaders(true) from apiHelpers for authenticated requests.
7. Always check result.sucesso before updating state (API responses use Portuguese keys).
8. Always export both the singleton instance and the class from services.
9. Always export the context as default and the provider as named export.
10. Always add JSDoc comments to service methods and type interfaces.

Step 1: Create Types

File: src/types/{entity}.ts

/** {Entity} Types — Types for the {entity description} system */

// Enums (if needed)
export enum {Entity}StatusEnum {
  Unknown = 0,
  Active = 1,
  Inactive = 2,
}

// Core Entity
/** Main {entity} information */
export interface {Entity}Info {
  {entity}Id: number;
  name: string;
  // ... other fields with JSDoc comments
}

// DTOs
/** Data required to create a new {entity} (no ID) */
export interface {Entity}InsertInfo {
  name: string;
  // ... fields required for creation
}

/** Data required to update an existing {entity} (includes ID) */
export interface {Entity}UpdateInfo {
  {entity}Id: number;
  name: string;
  // ... fields required for update
}

// API Response Types — always include sucesso, mensagem, erros (Portuguese keys)
export interface {Entity}ListResult {
  {entities}: {Entity}Info[];
  sucesso: boolean;
  mensagem: string | null;
  erros: string[] | null;
}

export interface {Entity}GetResult {
  {entity}: {Entity}Info;
  sucesso: boolean;
  mensagem: string | null;
  erros: string[] | null;
}

/** Status-only operation result (import from existing types file if already defined) */
export interface StatusResult {
  sucesso: boolean;
  mensagem: string;
  erros: string[] | null;
}