Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
278 lines (197 loc) · 6.23 KB

ARCHITECTURE.md

File metadata and controls

278 lines (197 loc) · 6.23 KB
Tipo: Documentación Técnica
Categoría: Arquitectura del Sistema
Versión: 1.0
Propósito: Documentación de decisiones arquitectónicas y diseño del sistema
Objetivo: Proporcionar visión clara de la arquitectura y decisiones técnicas
Fecha actualización: 2026-03-25

ARCHITECTURE

Propósito

Documentación de decisiones arquitectónicas, patrones de diseño, y estructura del sistema THYROX.

Objetivo: Que nuevos desarrolladores comprendan la arquitectura y tomen decisiones consistentes.

Visión General de Arquitectura

THYROX es un template profesional para gestión de proyectos con Claude Code. La arquitectura se divide en componentes independientes:

Backend: Node.js + Express
Frontend: (Por definir)
Base de Datos: PostgreSQL
DevOps: GitHub Actions + Docker
Documentación: Markdown versionado en Git

Componentes Principales

API Sub-proyecto (./ api/)

REST API construida con Node.js y Express.

Estructura:
src/routes/ - Definición de endpoints
src/controllers/ - Manejadores de requests
src/services/ - Lógica de negocio
src/middleware/ - Middleware de Express
src/models/ - Modelos de datos

Build Sub-proyecto (./ build/)

Configuración de build, testing, y deployment.

Incluye:
Scripts de setup, compilación, testing
Configuración GitHub Actions
Docker setup y compose
Ambiente variables

Documentación (./ docs/)

Documentación técnica y guías.

Incluye:
API.md - Endpoints y autenticación
BUILD.md - Guía de build y deployment
ARCHITECTURE.md - Decisiones arquitectónicas
CONTRIBUTING.md - Guía de contribución

Decisiones Arquitectónicas

1. Monorepo con Sub-proyectos

Decisión: Mantener API y Build como sub-proyectos independientes dentro de un monorepo.

Razones:
Facilita desarrollo independiente
Permite versioning separado
Documentación colocalizada
CI/CD pipeline unificado

2. Markdown como Fuente de Verdad

Decisión: Toda documentación en Markdown versionado en Git.

Razones:
Versionable y auditable
Sin dependencias externas
GitHub lo renderiza nativamente
Fácil de convertir a otros formatos

3. ROADMAP.md como Plan Maestro

Decisión: ROADMAP.md es la fuente única de verdad para el estado del proyecto.

Razones:
Single source of truth
Fácil de actualizar
Histórico completo en Git
Accesible para todo el equipo

4. Conventional Commits

Decisión: Usar Conventional Commits para estandarización.

Razones:
Commits legibles y estructurados
Facilita changelog automático
Semántica clara
Herramientas integran fácilmente

5. Claude Code Native

Decisión: Usar features nativas de Claude Code, no librerías externas.

Razones:
Reduce dependencias
Facilita mantenimiento
No requiere configuración adicional
Integración directa

Patrones de Diseño

API REST

  • Endpoints: RESTful design
  • Autenticación: API Keys + Bearer tokens
  • Validación: Input validation en middleware
  • Error Handling: Standardized error responses
  • Versionado: /v1/ prefix en URLs

Base de Datos

  • ORM: (Por definir)
  • Migraciones: Git-based (no automáticas)
  • Backup: Daily snapshots
  • Índices: Optimizados para queries comunes

Estructura de Código

Separación de concerns:
Routes → Controllers → Services → Models
Cada capa con responsabilidad clara
Inyección de dependencias
Testing en cada nivel

Convenciones

Naming

Archivos: kebab-case.md
Carpetas: lowercase-folders/
Variables: camelCase
Constantes: CONSTANT_CASE
Classes: PascalCase

Estructura de Carpetas

project/
├── api/
│   ├── src/
│   │   ├── routes/
│   │   ├── controllers/
│   │   ├── services/
│   │   ├── middleware/
│   │   ├── models/
│   │   └── utils/
│   ├── tests/
│   └── package.json
├── build/
│   ├── scripts/
│   ├── config/
│   └── Dockerfile
├── docs/
├── .claude/
│   ├── context/
│   ├── skills/
│   └── prds/
└── reference/

Escalabilidad

Crecimiento Horizontal

API: Stateless design para fácil escalado
BD: Connection pooling
Cache: Redis para datos frecuentes
CDN: Para assets estáticos

Crecimiento Vertical

Code: Módulos independientes
DB: Índices optimizados
Cache: Estrategia inteligente
Monitoring: Métricas clave

Seguridad

Principios

Least Privilege: Mínimos permisos necesarios
Defense in Depth: Múltiples capas
Secure by Default: Seguridad es el default
Audit Trail: Logging de cambios

Implementación

HTTPS: Siempre en producción
API Keys: Rotación periódica
Input Validation: En todos los endpoints
CORS: Configurado restrictivamente
Rate Limiting: Para prevenir abuse

Deployment

Ambientes

Desarrollo: Local machine
Staging: Pre-producción para testing
Producción: Live environment

CI/CD Pipeline

  1. Commit: Push a GitHub
  2. Test: Automated tests corren
  3. Build: Docker image se construye
  4. Deploy: Auto-deploy a staging
  5. Review: Manual approval
  6. Release: Deploy a producción

Rollback

  • Versiones anteriores en registry
  • Database migrations reversibles
  • Health checks antes de considerar ready
  • Monitoreo post-deployment

Monitoreo y Logging

Logs

Application: Estructura JSON
Access: Request/response logs
Error: Stack traces con contexto
Audit: Cambios críticos

Métricas

Performance: Response times
Availability: Uptime y errors
Business: User counts, transactions
Infrastructure: CPU, memory, disk

Roadmap Futuro

Phase 1 (Actual): Estructura base
Phase 2: API completa
Phase 3: Build & deployment
Phase 4: Frontend
Phase 5: Escalabilidad

Última Actualización: 2026-03-25
Próxima Review: 2026-04-25