¶ Paradox - Gestión de Proyectos Open Source
Nota importante:
Esta es una plantilla estimada de cómo se verá la documentación de Paradox. El stack tecnológico, arquitectura y configuraciones descritas aquí son referenciales y están sujetas a cambios durante el desarrollo del proyecto.
¶ 📋 Descripción General
Paradox es una herramienta de gestión de proyectos moderna y open-source desarrollada internamente. Permite a los equipos rastrear issues, ejecutar ciclos de desarrollo, y gestionar roadmaps de producto sin la complejidad de herramientas tradicionales.
¶ ✨ Características Principales
¶ 🎯 Issues & Work Items
Gestión completa de tareas con editor rico, sub-propiedades y referencias cruzadas
¶ 📈 Cycles
Sprints con burn-down charts y métricas de progreso en tiempo real
¶ 📦 Modules
Divide proyectos complejos en módulos más pequeños y manejables
¶ 👁️ Custom Views
Crea y comparte vistas personalizadas con filtros avanzados
¶ 📄 Pages
Documentación colaborativa con editor rico y capacidades de IA
¶ 📊 Analytics
Insights en tiempo real con visualizaciones y métricas de equipo
¶ 🏗️ Arquitectura del Sistema
¶ Diagrama de Capas
┌─────────────────────────────────────────────────────────────────┐
│ CAPA FRONTEND │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Web │ │ Admin │ │ Space │ │ Live │ │
│ │ :3000 │ │ :3001 │ │ :4000 │ │ :3002 │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────┘
↕
┌─────────────────────────────────────────────────────────────────┐
│ CAPA API │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ API │ │ Worker │ │ Beat │ │ Migrator │ │
│ │ :8000 │ │ │ │ Worker │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────┘
↕
┌─────────────────────────────────────────────────────────────────┐
│ CAPA DE SERVICIOS │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │PostgreSQL│ │ Redis/ │ │ RabbitMQ │ │ MinIO │ │
│ │ :5432 │ │ Valkey │ │ :5672 │ │ :9000 │ │
│ │ │ │ :6379 │ │ │ │ │ │
│ └──────────┘ └──────────┘ └──────────┘ └──────────┘ │
└─────────────────────────────────────────────────────────────────┘
¶ ⚙️ Stack Tecnológico
¶ Frontend
| Categoría | Tecnología | Versión | Descripción |
|---|---|---|---|
| Framework | React | 18.3.1 | Librería UI principal |
| Router | React Router | 7.9.5 | Sistema de navegación |
| Build Tool | Vite | 7.1.11 | Build tool y dev server |
| Estado | MobX | 6.12.0 | State management |
| Data Fetching | SWR | 2.2.4 | Sincronización de datos |
| HTTP Client | Axios | 1.12.0 | Cliente HTTP |
| Estilos | Tailwind CSS | 3.x | Framework CSS utility-first |
| Lenguaje | TypeScript | 5.7.2 | JavaScript tipado |
¶ Backend
| Categoría | Tecnología | Versión | Descripción |
|---|---|---|---|
| Framework | Django | 4.2.26 | Framework web Python |
| API | Django REST Framework | 3.14.0 | API REST |
| Base de Datos | PostgreSQL | 15.7 | Base de datos principal |
| Cache | Redis/Valkey | 7.2.4 | Cache y message broker |
| Queue | Celery | 5.3.6 | Task queue distribuido |
| Message Broker | RabbitMQ | 3.13.x | Message queuing |
| Storage | MinIO | Latest | Object storage (S3-compatible) |
| Lenguaje | Python | 3.8+ | Lenguaje backend |
¶ DevOps & Herramientas
| Categoría | Tecnología | Descripción |
|---|---|---|
| Contenedores | Docker | Containerización |
| Orquestación | Docker Compose | Multi-container orchestration |
| Monorepo | Turborepo | Build system |
| Package Manager | pnpm | Gestor de paquetes Node.js |
| Linting (Backend) | Ruff | Python linter y formatter |
¶ 💻 Aplicación Frontend
¶ Estructura del Proyecto
apps/web/
├── core/
│ ├── components/
│ │ ├── issues/ # 316 componentes
│ │ ├── cycles/ # 42 componentes
│ │ ├── modules/ # 47 componentes
│ │ ├── gantt-chart/ # 37 componentes
│ │ └── analytics/ # 33 componentes
│ ├── hooks/
│ ├── stores/ # MobX stores
│ └── services/ # API services
├── public/
├── vite.config.ts
└── package.json
¶ Configuración Principal
{
"name": "@paradox/web",
"version": "1.1.0",
"scripts": {
"dev": "react-router dev",
"build": "react-router build",
"start": "serve ./build/client"
},
"dependencies": {
"react": "18.3.1",
"react-router": "7.9.5",
"mobx": "6.12.0",
"swr": "2.2.4",
"axios": "1.12.0"
}
}
¶ Tecnologías de Gestión de Estado
- MobX: State management reactivo para UI complejo
- SWR: Cache, revalidación y sincronización de datos con la API
- React Context: Estado global compartido entre componentes
¶ 🗄️ Modelos de Datos
¶ User
Tipo: Core
Campos principales:
id(UUID)usernameemaildisplay_nameavatar
¶ Workspace
Tipo: Core
Campos principales:
nameslugorganization_sizelogo
¶ Project
Tipo: Core
Campos principales:
identifiernamedescriptionnetwork(público/privado)
¶ Issue
Tipo: Core
Campos principales:
sequence_idnamedescription_htmlpriority,state,labels
¶ Cycle
Tipo: Feature
Campos principales:
namestart_date,end_dateprogress_snapshot
¶ Module
Tipo: Feature
Campos principales:
namedescriptionstatus,lead
¶ Page
Tipo: Feature
Campos principales:
nameblocks(JSON)access(público/privado)
¶ Estimate
Tipo: Configuration
Campos principales:
namepoints(JSON)type
¶ 🐳 Despliegue con Docker
¶ Requisitos
- Docker Engine
- Node.js 22+
- pnpm 10.21.0+
- Mínimo 12 GB RAM
¶ Servicios
| Servicio | Puerto | Descripción |
|---|---|---|
| web | 3000 | Frontend principal |
| admin | 3001 | Panel de administración |
| api | 8000 | Django REST API |
| paradox-db | 5432 | PostgreSQL 15 |
| paradox-redis | 6379 | Redis/Valkey |
| paradox-minio | 9000 | Object Storage |
¶ Instalación
# 1. Setup inicial
./setup.sh
# 2. Copiar archivo de entorno
cp .env.example .env
# 3. Iniciar servicios
docker-compose -f docker-compose-local.yml up -d
# 4. Ejecutar migraciones
docker-compose -f docker-compose-local.yml exec api python manage.py migrate
# 5. Crear superusuario
docker-compose -f docker-compose-local.yml exec api python manage.py createsuperuser
¶ URLs de Acceso
- Frontend: http://localhost:3000
- Admin Panel: http://localhost:3001/god-mode
- API: http://localhost:8000/api
- MinIO Console: http://localhost:9000
¶ ⚡ Variables de Configuración
¶ Variables Principales
| Variable | Valor por Defecto | Descripción |
|---|---|---|
POSTGRES_USER |
paradox | Usuario de PostgreSQL |
POSTGRES_PASSWORD |
paradox | Contraseña de PostgreSQL |
POSTGRES_DB |
paradox | Nombre de la base de datos |
REDIS_HOST |
paradox-redis | Host de Redis |
AWS_S3_BUCKET_NAME |
uploads | Bucket de MinIO/S3 |
USE_MINIO |
1 | Usar MinIO en lugar de S3 |
¶ Archivo .env
# Base de datos
POSTGRES_USER=paradox
POSTGRES_PASSWORD=paradox
POSTGRES_DB=paradox
# Redis
REDIS_HOST=paradox-redis
REDIS_PORT=6379
# MinIO / S3
USE_MINIO=1
AWS_ACCESS_KEY_ID=access-key
AWS_SECRET_ACCESS_KEY=secret-key
AWS_S3_BUCKET_NAME=uploads
AWS_S3_ENDPOINT_URL=http://paradox-minio:9000
# Django
SECRET_KEY=your-secret-key-here
DEBUG=True
¶ 📚 Documentación Adicional
¶ 📄 Licencia
Este proyecto está licenciado bajo AGPL-3.0. Consulta el archivo LICENSE para más detalles.
¶ 📞 Soporte
Para soporte y preguntas:
- Issues: GitHub Issues
- Discord: Únete a nuestro servidor
- Email: support@paradox.dev
Última actualización: 27 Nov 2025 | Versión: 1.1.0
Desarrollado por el equipo de Paradox