Cash Flow
Aquí encontrarás la documentación general del proyecto, para los casos específicos puedes visitar la documentación específica para:
Este documento reúne la información esencial acerca de Cashflow, tanto a nivel de su arquitectura de software (frontend y backend), como de la configuración requerida para su despliegue en AWS. Se incluyen diagramas de la arquitectura interna del proyecto, diagramas de casos de uso y un diagrama de infraestructura para guiar la puesta en producción en la nube.
Tabla de Contenidos
Introducción
Cashflow es una aplicación completa que permite a los usuarios:
- Registrar movimientos financieros (ingresos y gastos).
- Clasificar dichos movimientos por categorías.
- Subir imágenes de facturas/recibos para procesar la información de forma automática con OCR.
- Analizar reportes de gastos e ingresos de manera más eficiente.
Este proyecto se compone de:
- Frontend: Interfaz en React (o tecnología similar), responsable de la experiencia de usuario.
- Backend: API REST en Node.js (o la tecnología especificada) con base de datos PostgreSQL.
Objetivos del Proyecto
- Proveer una herramienta personalizable de gestión financiera que no esté limitada por las opciones típicas del mercado.
- Automatizar la captura de datos financieros mediante OCR, para simplificar la creación de movimientos.
- Facilitar un despliegue en la nube (AWS) con escalabilidad y alta disponibilidad.
- Mantener una arquitectura limpia (Hexagonal) que permita incorporar nuevas funciones sin comprometer la estabilidad del sistema.
Arquitectura General
Arquitectura Interna (Hexagonal)
La arquitectura hexagonal facilita la separación de la lógica de negocio (Dominio) de los adaptadores de entrada (Controllers, CLI, etc.) y salida (Base de Datos, OCR, Servicios Externos). Aquí se muestra un diagrama simplificado:
flowchart LR
subgraph Dominio
DomainLogic[Logica de Negocio] --> PuertoIn[Puerto de Entrada]
DomainLogic --> PuertoOut[Puerto de Salida]
end
subgraph AdaptadoresDeEntrada
UI(Frontend / Controllers)
CLI(CLI / Comandos)
end
subgraph AdaptadoresDeSalida
DBAdapter(Adaptador BD)
OCRAdapter(Adaptador OCR)
ExternalServices(Servicios Externos)
end
UI --> PuertoIn
CLI --> PuertoIn
PuertoOut --> DBAdapter
PuertoOut --> OCRAdapter
PuertoOut --> ExternalServices
- Dominio: Contiene la lógica principal (cálculo de finanzas, validaciones, reglas de negocio).
- Puertos: Definen interfaces para que el Dominio interactúe con el exterior, sin conocer detalles de implementación.
- Adaptadores: Implementan físicamente estas interfaces (HTTP Controllers para entrada, DB u OCR para salida).
Casos de Uso Principales
El flujo general de cómo interactúa el usuario con la aplicación se muestra en este diagrama de secuencia:
sequenceDiagram
actor U as Usuario
participant Front as Frontend
participant Back as Backend
participant DB as Base de Datos
U->>Front: Solicita registrar nuevo movimiento
Front->>Back: POST /api/movements
Back->>DB: Valida y guarda el movimiento
DB-->>Back: Retorna movimiento registrado
Back-->>Front: 201 Created (movimiento creado)
Front-->>U: Muestra confirmación
La lógica es similar para otros casos de uso, como inicio de sesión, subida de facturas para OCR, etc.
Frontend
El Frontend de Cashflow:
- Desarrollado en React (o framework similar).
- Se organiza en carpetas como
components/
,pages/
,services/
, etc. - Se conecta al Backend mediante llamadas HTTP (
fetch
oaxios
).
Para más detalles, consulta la Documentación del Frontend donde se explica:
- Estructura de archivos y organización del proyecto.
- Componentes principales y estilo (Material UI, Tailwind, etc., según configuración).
- Flujos de usuario (Crear movimiento, subir factura, ver reportes).
- Configuración de entorno mediante archivos
.env
.
Backend
El Backend de Cashflow:
- Está desarrollado con Node.js (u otra tecnología compatible).
- Se conecta a PostgreSQL como base de datos principal.
- Expone una serie de endpoints REST para:
- Registro/Iniciar Sesión (Auth).
- Gestión de categorías y movimientos.
- Procesamiento de imágenes OCR.
Para mayor detalle, revisa la Documentación del Backend, donde se cubre:
- Modelado de datos (User, Movement, Category, OCRInvoice).
- Estructura de carpetas (controllers, services, routes, etc.).
- Configuración de variables de entorno (DB_HOST, DB_USER, PORT, etc.).
- Endpoints disponibles y ejemplos de petición/respuesta.
- Diagrama ER mostrando las relaciones de tablas en PostgreSQL.
Despliegue en AWS
Para habilitar un entorno escalable y robusto, se propone AWS como proveedor cloud. A continuación, se presentan los pasos recomendados para desplegar la solución.
Diagrama de Infraestructura Cloud
flowchart LR
subgraph client["Cliente"]
user["👤 Usuario"]
end
subgraph vpc["VPC"]
subgraph public["Subredes Públicas"]
alb["🔄 Application\nLoad Balancer"]
end
subgraph private["Subredes Privadas"]
subgraph ecs_cluster["Cluster ECS"]
ecs_frontend["🖥️ ECS Frontend\nTask Definition"]
ecs_backend["⚙️ ECS Backend\nTask Definition"]
end
rds["💾 RDS PostgreSQL"]
end
end
subgraph storage["Almacenamiento"]
s3["📁 S3 Bucket\nFacturas"]
ecr["📦 ECR\nImágenes Docker"]
end
subgraph processing["Procesamiento"]
ocr["🔍 Servicio OCR"]
end
%% Conexiones
user --> alb
alb --> ecs_frontend
alb --> ecs_backend
ecs_frontend --> ecr
ecs_backend --> ecr
ecs_backend --> rds
ecs_backend --> s3
s3 --> ocr
%% Estilos
classDef vpc fill:#f5f5f5,stroke:#333,stroke-width:2px
classDef public fill:#e1f5fe,stroke:#333
classDef private fill:#e8f5e9,stroke:#333
classDef storage fill:#fff3e0,stroke:#333
classDef processing fill:#f3e5f5,stroke:#333
class vpc vpc
class public public
class private private
class storage storage
class processing processing
- El Usuario interactúa con la aplicación (Frontend).
- Application Load Balancer (ALB) distribuye la carga entrante a instancias de contenedores en ECS.
- ECS aloja contenedores Docker del Frontend y Backend (opcionalmente se pueden dividir servicios).
- ECR (Elastic Container Registry) almacena las imágenes Docker.
- RDS (PostgreSQL) gestiona la base de datos.
- S3 puede utilizarse para almacenar imágenes de facturas, recibos u otros archivos estáticos.
- El Servicio OCR puede ser un contenedor aparte en ECS o un servicio externo (depende de la implementación actual).
Configuración de Servicios AWS
Amazon ECR
- Crear un repositorio para cashflow-front y otro para cashflow-back.
- Generar tokens de autenticación para Docker e iniciar sesión en ECR.
- Construir las imágenes Docker de frontend y backend; etiquetarlas y subirlas a ECR.
Amazon ECS (Fargate o EC2)
- Crear una ECS Cluster en modo Fargate (serverless) o EC2 (requiere gestionar instancias).
- Configurar Task Definitions para frontend y backend; apuntar a las imágenes ubicadas en ECR.
- Definir Service para cada Task Definition, especificando cuánto CPU/Memoria se asigna.
- Configurar la Networking (VPC, subnets, security groups) para acceso seguro.
Amazon RDS
- Crear una instancia de PostgreSQL en Amazon RDS.
- Definir el tamaño (db.t3.micro para entornos de prueba o mayor en producción).
- Asegurarse de habilitar la conexión desde ECS a RDS mediante la Security Group adecuada.
- Configurar variables de entorno en ECS para usar
DB_HOST
,DB_USER
,DB_PASSWORD
, etc.
Amazon S3
- Crear un bucket para almacenar los archivos de facturas/recibos.
- Definir políticas de acceso para el backend (o un rol de IAM asociado al servicio ECS).
- Integrar la carga/descarga de archivos desde la aplicación (backend + frontend).
Balanceador de Carga y Certificados SSL
- Crear un Application Load Balancer (ALB) que reciba tráfico HTTP/HTTPS.
- Configurar un Listener en el puerto
443
con certificado SSL (vía AWS Certificate Manager). - Dirigir el tráfico a la Target Group asociada a la tarea de ECS (frontend o backend).
- Para el Frontend estático, se puede usar S3 + CloudFront en lugar de ECS, o incluirlo en un contenedor Docker sirviendo la app.
Flujo de Despliegue Paso a Paso
1
2
3
4
5
6
7
8
9
10
11
12
13
14
# 1. Construir imágenes Docker (ejemplo con backend)
docker build -t cashflow-back:latest .
# 2. Autenticarse con AWS ECR
aws ecr get-login-password --region <region> | docker login --username AWS --password-stdin <your_account_id>.dkr.ecr.<region>.amazonaws.com
# 3. Etiquetar y subir imagen
docker tag cashflow-back:latest <your_account_id>.dkr.ecr.<region>.amazonaws.com/cashflow-back:latest
docker push <your_account_id>.dkr.ecr.<region>.amazonaws.com/cashflow-back:latest
# 4. Repetir el proceso para la imagen frontend
docker build -t cashflow-front:latest .
docker tag cashflow-front:latest <your_account_id>.dkr.ecr.<region>.amazonaws.com/cashflow-front:latest
docker push <your_account_id>.dkr.ecr.<region>.amazonaws.com/cashflow-front:latest
- ECR: Definir repositorios para
cashflow-back
ycashflow-front
. - IAM Roles: Crear roles para ECS y RDS, permitiendo acceso a ECR y a la base de datos.
- ECS Cluster:
- Crear cluster en Fargate.
- Crear Task Definitions para cada contenedor, indicando la imagen, puertos y variables de entorno (
DB_HOST
,OCR_API_KEY
, etc.).
- Servicios:
- Definir un servicio ECS para el backend y otro para el frontend.
- Configurar Auto Scaling si se requiere alta disponibilidad.
- ALB (Load Balancer):
- Asociar un target group para el backend en el puerto 3000 (por ejemplo).
- Asignar listener HTTPS en el ALB y conectar la ruta
/api/*
→ Backend ECS. - (Opcional) Asignar la ruta
/
→ Frontend ECS o servir el frontend en S3/CloudFront.
- Comprobar:
- Probar la URL generada en el ALB (o dominio personalizado con Route53).
- Validar conexión con la base de datos y el correcto funcionamiento del OCR.
Conclusión
La presente documentación unifica:
- Arquitectura del proyecto (Frontend y Backend).
- Principales casos de uso y diagramas de interacción.
- Guía de despliegue en AWS con sus componentes clave (ECR, ECS, RDS, S3, ALB).
Con esta base, es posible escalar el proyecto de forma modular, manteniendo las ventajas de la arquitectura hexagonal y aprovechando los servicios de AWS para asegurar alta disponibilidad, confiabilidad y un proceso de entrega continuo.
Para dudas o sugerencias, se recomienda abrir un issue en los repositorios de Cashflow-Back o Cashflow-Front.