Plan — LedgerLab

Volver a README · 08 Proyectos

Objetivo: construir una API de finanzas personales que importe transacciones desde archivos CSV/OFX, las categorice con reglas y genere reportes programados.

Estado: planificación. Proyecto de cierre en 4 semanas.

1. Alcance

1. Registro e inicio de sesión con JWT.
2. CRUD de cuentas, categorías, transacciones y presupuestos.
3. Importación de archivos CSV/OFX.
4. Worker en Go para parseo y carga masiva.
5. Reglas de categorización automática.
6. Detección de transacciones recurrentes.
7. Reportes mensuales por categoría.
8. Alertas de presupuesto excedido.

2. Fuera de alcance

• Conexión directa a bancos.
• Scraping de homebanking.
• Multi-moneda con conversión en tiempo real.
• Facturación o planes de pago.
• App móvil nativa.

3. Arquitectura

Frontend (React/Next.js)
        │
        ▼
API Python (FastAPI) ──────► PostgreSQL
        │
        ├── Redis + Celery (jobs)
        │
        └── Worker Go (CSV/OFX)
                │
                ▼
           PostgreSQL

Flujo de importación:

Usuario sube CSV → API guarda archivo → encola job
                                              │
                                              ▼
                                    Worker Go parsea y normaliza
                                              │
                                              ▼
                                    Inserta transacciones (dedup)
                                              │
                                              ▼
                                    Actualiza estado del import

4. Modelo de datos

Tabla	Campos principales
users	id, email, password_hash, created_at
accounts	id, user_id, name, type, currency
categories	id, user_id, name, parent_id
transactions	id, account_id, date, amount_cents, description, category_id, source, external_id, status
rules	id, user_id, field, operator, value, category_id, priority
budgets	id, user_id, category_id, month, amount_cents
imports	id, user_id, filename, status, total_rows, processed_rows, error
recurring	id, user_id, merchant, amount_cents, frequency, next_date

5. Componentes

Componente	Responsabilidad
Auth	Registro, login y JWT
Accounts	CRUD de cuentas
Transactions	CRUD y filtros por fecha, cuenta y categoría
Import API	Recibir archivo y encolar job
Worker Go	Parsear CSV/OFX, normalizar y cargar
Rules engine	Asignar categoría según reglas
Recurring detector	Detectar suscripciones y pagos periódicos
Reports	Totales por categoría y mes
Alerts	Avisar presupuestos excedidos
Scheduler	Generar reportes y revisar presupuestos

6. Hitos

Semana	Entregable	Criterio de cierre
1	Auth + CRUD de cuentas/categorías/transacciones + DB	Se registra un usuario y se cargan transacciones manualmente
2	Upload CSV + worker Go + estado del import + dedup	Un CSV de 100 filas se procesa sin duplicados
3	Reglas de categorización + recurrentes + reportes + alertas	Las reglas asignan categorías y se genera un reporte
4	Dashboard + Docker + CI/CD + deploy + docs + demo	URL pública con importación y reporte funcionando

7. Criterios de aceptación

• Registro e inicio de sesión.
• CRUD de cuentas, categorías y transacciones.
• Importar un CSV real de al menos 100 filas.
• El worker Go procesa el archivo y actualiza el estado.
• Reimportar el mismo archivo no duplica transacciones.
• Una regla asigna categoría automáticamente.
• Se detecta al menos una transacción recurrente.
• Se genera un reporte mensual.
• Tests en Python y en Go.
• CI verde.
• README con capturas y URL de demo.

8. Decisiones técnicas

• Python + FastAPI: rápido para CRUD, validación y reglas.
• Go para la ingesta: parseo y carga masiva con bajo consumo de memoria.
• PostgreSQL: integridad relacional y consultas de reportes.
• Redis + Celery: trabajos asíncronos y reintentos.
• Montos en centavos: evita errores de punto flotante.
• external_id: deduplicación de importaciones.
• Reglas simples primero: campo + operador + valor; sin motor de expresiones.

9. Riesgos

Riesgo	Mitigación
Formatos CSV distintos	Soportar un formato base y documentarlo
Duplicados al reimportar	external_id único por cuenta
Errores de redondeo	Guardar montos como enteros
Worker Go consume tiempo	Dejar la ingesta en Python como plan B
Datos financieros sensibles	No subir archivos reales al repositorio; usar datos de prueba

10. Próximo paso

1. Inicializar monorepo y Git.
2. Crear el esquema de base de datos y las migraciones.
3. Implementar auth y CRUD de cuentas.
4. Definir el formato CSV de entrada y los datos de prueba.
5. Primer commit con README y CI mínima.

Enlaces

• README
• 08 Proyectos
• Portafolio
• 000 Índice