Estructura del frontend

El frontend principal de Apolo está compuesto por:

portal-web: Portal web de auditoría, seguridad y observabilidad.
devs-portal: Sitio de documentación para desarrolladores (Docusaurus).

Portal Web (`portal-web`)

El proyecto portal-web es una aplicación React 18 que utiliza:

ITDS como librería de componentes corporativos.
TanStack Query para manejo de estado asíncrono y cacheo de datos.
BFF (bff-api) como backend principal.
Tailwind CSS para estilos utilitarios.

Patrón Arquitectónico

El proyecto sigue una arquitectura hexagonal (Ports & Adapters) con las siguientes capas:

┌─────────────────────────────────────────────┐
│            Presentation Layer               │
│         (Pages, Components, UI)             │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│          Application Layer                  │
│   (Contexts, Hooks, Service Hooks)          │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│            Domain Layer                     │
│      (Models, Interfaces, Enums)            │
└─────────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────────┐
│         Infrastructure Layer                │
│    (Clients, Adapters, Providers)           │
└─────────────────────────────────────────────┘

Flujo de Datos

Usuario → Interactúa con Components/Pages
Pages → Usa Contexts y Service Hooks
Service Hooks → Llama a Clients (servicios API)
Clients → Usa Adapters para transformar datos
Adapters → Convierte entre DTOs y Models del dominio

Estructura de Carpetas

apps/portal-web/
├── src/
│   ├── adapters/              # Transformadores de datos (DTOs ↔ Domain Models)
│   ├── app.tsx                # Componente raíz de la aplicación
│   ├── assets/                # Recursos estáticos (imágenes, iconos, SVGs)
│   ├── clients/               # Servicios para comunicación con APIs
│   ├── components/            # Componentes reutilizables (60+ componentes)
│   ├── config/                # Configuración y secretos de la aplicación
│   ├── constants/             # Constantes globales
│   ├── contexts/              # React Contexts para estado global
│   ├── core/                  # Lógica central y proveedores
│   ├── hooks/                 # Custom React Hooks
│   ├── locales/               # Archivos de internacionalización (i18n)
│   ├── main.tsx               # Punto de entrada de React
│   ├── models/                # Modelos del dominio (DTOs, interfaces, enums)
│   ├── pages/                 # Páginas de la aplicación (21 páginas)
│   ├── routes/                # Configuración de rutas y navegación
│   ├── service-hooks/         # Hooks para servicios con TanStack Query
│   ├── styles/                # Estilos globales
│   ├── translations/          # Sistema de traducción
│   ├── utils/                 # Utilidades y helpers
│   ├── index.html             # HTML principal
│   ├── input.css              # CSS de entrada de Tailwind
│   └── output.css             # CSS compilado de Tailwind
│
├── .eslintrc.json             # Configuración de ESLint
├── .swcrc                     # Configuración de SWC
├── jest.config.ts             # Configuración de Jest
├── postcss.config.js          # Configuración de PostCSS
├── project.json               # Configuración de NX
├── tailwind.config.js         # Configuración de Tailwind
├── tsconfig.json              # Configuración de TypeScript
└── webpack.config.js          # Configuración de Webpack

Descripción de Carpetas Principales

`adapters/`

Contiene funciones que transforman datos entre diferentes representaciones. Convierte respuestas de API (DTOs) a modelos del dominio y viceversa. Ejemplo: convertir user_response con snake_case a User con camelCase.

`assets/`

Almacena todos los recursos estáticos como imágenes, iconos SVG, logos y archivos multimedia. Organizado en subcarpetas por tipo (applications, help, partners, questions, solutions).

`clients/`

Servicios que manejan la comunicación con las APIs backend. Cada servicio encapsula las operaciones CRUD para un recurso específico (usuarios, proveedores, planes, etc.). Incluye mocks para desarrollo.

`components/`

Más de 60 componentes React reutilizables organizados por funcionalidad. Incluye componentes de UI (botones, inputs, modals), layout (header, sidebar), datos (tablas, paginación) y componentes de negocio específicos.

`config/`

Configuración de la aplicación y secretos. El archivo secrets.ts es generado automáticamente por Seki con variables de entorno. .configrc.json define qué secretos necesita el proyecto.

`constants/`

Constantes globales y configuraciones compartidas, como la configuración del cliente de TanStack Query.

`contexts/`

React Contexts para manejar estado global de la aplicación. Incluye contextos para autenticación, sesión, aplicación seleccionada, tema, usuario, proveedor, loading y más.

`core/`

Lógica central de la aplicación. Contiene los proveedores de datos para Refine (proxyDataProvider) que enrutan las operaciones CRUD a los servicios correctos.

`hooks/`

Custom hooks de React para reutilizar lógica común. Incluye hooks para drawers, tablas, local/session storage, media queries, click outside, disclosure, etc.

`locales/`

Archivos JSON con traducciones para internacionalización. Soporta español (es_ES) y portugués (pt_BR).

`models/`

Modelos del dominio organizados en:

dto/: Data Transfer Objects para requests y responses
enums/: Enumeraciones (países, marcas, business units)
interfaces/: Interfaces TypeScript para entidades del dominio
types/: Type aliases

`pages/`

21 páginas de la aplicación organizadas por funcionalidad:

Autenticación (login, recover-password, reset-password, etc.)
Dashboard (home, application selector)
Administración (users, modules, suppliers, plans, aids)
Módulos especiales (security-module, abm-admin-module)
Reportes (reports, security-reports, power-bi)

`routes/`

Configuración del sistema de rutas:

loadable.components.tsx: Componentes con lazy loading
private.route.tsx: Rutas protegidas con autenticación
public.route.tsx: Rutas públicas sin autenticación

`service-hooks/`

Hooks personalizados que usan TanStack Query para comunicarse con los servicios. Encapsulan las llamadas a la API con gestión de caché, estados de loading/error y refetch.

`styles/`

Estilos CSS globales de la aplicación.

`translations/`

Sistema de traducción con hook personalizado para usar las traducciones en componentes.

`utils/`

Funciones de utilidad organizadas por dominio:

business-unit: Utilidades de unidades de negocio
countrys: Manejo de países
date: Formateo y manipulación de fechas
events: Manejo de eventos
filters: Funciones de filtrado
format: Formateadores
mapper: Mappers de datos
menu: Utilidades de menú
object: Operaciones con objetos
requests: Utilidades para HTTP requests
status: Manejo de estados
table: Utilidades para tablas
translator: Traductor
validate: Validadores

Configuración

project.json

El proyecto está configurado con los siguientes targets de NX:

Build

{
	"executor": "@nx/webpack:webpack",
	"configurations": {
		"development": {
			"optimization": false,
			"sourceMap": true
		},
		"release": {
			"optimization": true,
			"sourceMap": false
		}
	}
}

Características:

Compilador: SWC (más rápido que Babel)
Output: dist/apps/portal-web
Assets copiados: assets/ y config/

Serve

Servidor de desarrollo con HMR (Hot Module Replacement) habilitado en modo desarrollo.

Secrets

Genera el archivo src/config/secrets.ts con variables de entorno usando Seki:

seki secrets generate -p=portal-web

Tailwind

Compila los estilos de Tailwind CSS en modo watch:

npx tailwindcss -i ./src/input.css -o ./src/output.css --watch

Webpack Config

Características especiales:

Separación de secretos: Los archivos config/secrets.ts se separan en un chunk independiente para facilitar la inyección de configuración en diferentes entornos.
Public Path dinámico:

Development: /
Production: /apolo-app-platcom-platform/web/portal-web/

Optimización de chunks: Configuración especial para separar el archivo de secretos.

Tailwind Config

{
  prefix: 'tw-',           // Prefijo para evitar conflictos
  important: true,         // Forzar especificidad
  corePlugins: {
    preflight: false       // Desactivar reset CSS
  }
}

Características Principales

1. Sistema de Autenticación

Flujo completo:

Login → Verificación → Selección de Aplicación → Dashboard

Rutas protegidas con soporte para roles y requisitos de aplicación seleccionada.

2. Sistema Multi-Tenant

Soporte para múltiples tenants
Selección de tenant por usuario
Filtrado de datos por tenant
Business units (Supermercado, Tiendas por Departamento y Mejoramiento del Hogar)
Países soportados: AR, CL, BR, CO, PE

3. Módulos Dinámicos

Carga dinámica de módulos basada en permisos del usuario. Los módulos se cargan solo si el usuario tiene los roles necesarios.

4. Sistema de Rutas

Tipos de rutas:

Públicas (PublicRoute): Accesibles sin autenticación, redirecciona a /home si está autenticado
Privadas (PrivateRoute): Requiere autenticación, soporta roles permitidos, puede requerir aplicación seleccionada, opción de layout o sin layout

5. Internacionalización (i18n)

Idiomas soportados:

Español (es_ES)
Portugués (pt_BR)

6. Manejo de Errores

Error Boundary en el nivel raíz
Detección de red con pantalla offline
Notificaciones de error consistentes

7. Gestión de Estado

Múltiples niveles:

Estado local: useState, useReducer
Estado de servidor: TanStack Query
Estado global: React Context
Estado de URL: React Router

8. Optimización de Performance

Lazy Loading de rutas
Memoización de componentes
Code Splitting automático
Chunk especial para secretos

Mejores Prácticas

TypeScript:

Siempre tipar props y state
Usar interfaces para objetos complejos
Evitar any

Componentes:

Un componente por archivo
Props desestructuradas
Usar React.FC o función regular
Memoizar componentes pesados

State Management:

Estado local para UI state
TanStack Query para server state
Context para estado global compartido
Evitar prop drilling

Performance:

Lazy loading de rutas
Memoización con React.memo
useMemo y useCallback cuando sea necesario
Virtualización para listas largas

Testing:

Test unitarios para utils
Test de integración para componentes
Test de hooks personalizados
Mockear servicios externos

Organización:

Carpetas por feature
Index files para exports
Nombres descriptivos
Colocación cercana (colocation)

Devs Portal (devs-portal)

devs-portal es una aplicación Docusaurus v3 montada dentro del monorepo:

apps/devs-portal/
├── docusaurus.config.js
├── sidebars.js
└── docs/
├──   intro/
├──   architecture/
├──   development/
├──   project-structure/
├──   api/
├──   contributing/
└──   references/

Aquí se centraliza toda la documentación para desarrolladores:

Intro / visión del proyecto.
Arquitectura (C4, contextos, contenedores).
Guías de desarrollo, Nx, Docker, secretos.
Estructura de backend y frontend (estas páginas).
Consumo de APIs (Swagger, Bruno, Postman).
Guías de contribución y estilo de código.

Convenciones de frontend

Consumo de datos siempre a través del BFF (bff-api), no directamente contra microservicios individuales.
Estado remoto gestionado con TanStack Query (queries/mutations tipadas).
Estilos con Tailwind + ITDS para mantener consistencia visual corporativa.
Rutas organizadas por feature, evitando un app.tsx monolítico.

Portal Web (portal-web)​

Patrón Arquitectónico​

Flujo de Datos​

Estructura de Carpetas​

Descripción de Carpetas Principales​

adapters/​

assets/​

clients/​

components/​

config/​

constants/​

contexts/​

core/​

hooks/​

locales/​

models/​

pages/​

routes/​

service-hooks/​

styles/​

translations/​

utils/​

Configuración​

project.json​

Build​

Serve​

Secrets​

Tailwind​

Webpack Config​

Tailwind Config​

Características Principales​

1. Sistema de Autenticación​

2. Sistema Multi-Tenant​

3. Módulos Dinámicos​

4. Sistema de Rutas​

5. Internacionalización (i18n)​

6. Manejo de Errores​

7. Gestión de Estado​

8. Optimización de Performance​

Mejores Prácticas​

Devs Portal (devs-portal)​

Convenciones de frontend​