# 02 - Arquitectura General

> Cómo se conectan todas las piezas de `proyectosacc`.

---

## 1. Diagrama general

Aquí tienes un diagrama en texto que muestra el flujo completo:

```
┌─────────────────────────────────────────────────────────────────────────┐
│                         INTERNET (usuarios)                             │
│                              ▼                                          │
│                    https://sacc.ccsoft.mx                               │
└─────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  AWS Route 53                                                          │
│  (traduce el dominio al destino correcto)                              │
└─────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  AWS CloudFront + ACM (SSL)                                            │
│  (distribuye el frontend globalmente y pone el candadito verde HTTPS)  │
└─────────────────────────────────────────────────────────────────────────┘
                                     │
                                     ▼
┌─────────────────────────────────────────────────────────────────────────┐
│  S3 Static Website Hosting                                             │
│  (almacena y sirve el frontend React compilado)                        │
└─────────────────────────────────────────────────────────────────────────┘


FLUJO DE LA API (desde el navegador o la app)
=============================================

┌─────────────────┐      ┌─────────────────┐      ┌─────────────────┐
│  Navegador/app  │─────▶│  EC2 T3.small   │─────▶│  RDS MariaDB    │
│  (llama a /api) │      │  (API backend)  │      │  (base de datos)│
└─────────────────┘      └─────────────────┘      └─────────────────┘
                              │
                              │ Nginx Proxy (solo API, puerto 8080)
                              ▼
                       Servicio systemd
                       (usuario osiris)


OTRO FLUJO: El pipeline de despliegue
=====================================

┌──────────────┐     ┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Bitbucket   │────▶│  Pipeline    │────▶│  S3 Buckets  │────▶│  EC2 T3      │
│  (código)    │     │  (7 pasos)   │     │  (frontend + │     │  (API)       │
│              │     │              │     │  artefactos) │     │              │
└──────────────┘     └──────────────┘     └──────────────┘     └──────────────┘
                                          │                      ▲
                                          │                      │
                                          ▼                      │
                                    CloudFront invalidation      │
                                    (actualiza cache global)     │
```

---

## 2. Explicación de cada pieza

> 💡 **Dato clave**: aunque CloudFront sirve principalmente el frontend desde S3, también tiene una regla especial (`/api/*`) que envía las peticiones de la API directamente a la EC2. Así todo el tráfico de `sacc.ccsoft.mx` pasa por un solo punto.

### 🔷 Bitbucket
Es el "banco" donde se guarda el código fuente de SACC.
- Los desarrolladores suben sus cambios aquí.
- Cuando hay un cambio nuevo, Bitbucket "despierta" el pipeline.

### 🔷 Pipeline de Bitbucket (7 pasos)
Es el robot que hace todo el trabajo:
1. Prepara la imagen de compilación.
2. Descarga los repositorios.
3. Instala dependencias.
4. **Compila el frontend React (`npm run build`) y la API backend (`./gradlew bootJar`).**
5. **Sube el frontend al bucket S3 y el artefacto de la API a S3.**
6. Se conecta por SSH al servidor EC2 para desplegar la API.
7. **Invalida la caché de CloudFront, reinicia la API y verifica que todo esté saludable.**

### 🔷 S3 Bucket
Es un "almacén" de AWS con dos trabajos en `proyectosacc`:
1. **Sirve el frontend React** como un sitio web estático.
2. **Guarda los artefactos** de la API generados por el pipeline.
- También sirve como respaldo de versiones anteriores.

### 🔷 CloudFront
Es la red de distribución de contenido (CDN) de AWS.
- **Rol**: Toma los archivos del frontend desde S3 y los distribuye por todo el mundo de forma rápida y segura.
- También maneja el HTTPS con el certificado de ACM.

### 🔷 EC2 T3.small
Es el servidor virtual de AWS donde **solo vive la API/backend**.
- **Tipo**: `t3.small` (2 vCPU, 2 GB RAM).
- **Sistema operativo**: Ubuntu 22.04 LTS.
- **Rol**: Ejecuta el servicio de la API (Java) en el puerto `8080`.
- Nginx en la EC2 solo actúa como proxy hacia la API, **no sirve el frontend React**.

### 🔷 RDS MariaDB
Es la base de datos gestionada por AWS.
- **Tipo**: `db.t3.micro`.
- **Rol**: Guarda toda la información de la aplicación (clientes, facturas, usuarios, etc.).
- La EC2 se conecta a ella por la red interna de AWS.

### 🔷 Route 53
Es el servicio de DNS de AWS.
- **Rol**: Cuando un usuario escribe `sacc.ccsoft.mx`, Route 53 le dice al navegador que debe ir a **CloudFront** (no directamente a la EC2).
- Es como la "guía telefónica" de internet.

### 🔷 ACM (AWS Certificate Manager)
Es el servicio que gestiona los certificados SSL.
- **Rol**: Permite que `https://sacc.ccsoft.mx` funcione con el candadito verde.
- El certificado se adjunta a **CloudFront**, no a Nginx en la EC2.

---

## 3. Integración con proyectos CI/CD compartidos

`proyectosacc` se conecta con otros repositorios de CI/CD de Cómputo Contable Soft que le prestan "herramientas y ladrillos" ya hechos:

- **`ci-cd-commons`**: scripts base, utilerías como `telegram_alert.sh` y `logger_bash.sh`, y buenas prácticas de pipeline.
- **`ci-cd-saac4`**: módulos de Terraform, patrones de infraestructura AWS y scripts de despliegue adaptados para la familia de aplicaciones SACC.

Esto evita reinventar la rueda en cada proyecto y mantiene todo alineado con los estándares de la empresa.

---

## 4. ¿Por qué cada pieza existe?

| Pieza | ¿Por qué la necesitamos? |
|-------|--------------------------|
| Bitbucket | Para guardar el código y activar el pipeline automáticamente. |
| Pipeline | Para que nadie tenga que copiar archivos a mano. |
| S3 | Para servir el frontend React y guardar los artefactos de la API de forma segura. |
| CloudFront | Para distribuir el frontend rápidamente por todo el mundo con HTTPS. |
| EC2 T3 | Es el servidor donde corre la API backend. Sin él, no hay dónde procesar las peticiones de datos. |
| RDS | Es mejor que instalar la base de datos en la misma EC2 porque AWS la respalda, actualiza y monitorea automáticamente. |
| Route 53 | Para que los usuarios no tengan que memorizar una IP numérica. |
| ACM | Para que la conexión sea segura (HTTPS) y proteger los datos de los usuarios. |
| Nginx | Para recibir las peticiones a la API y pasarlas al servicio backend en el puerto 8080. |

---

*Anterior: [`01-que-es-proyectosacc.md`](01-que-es-proyectosacc.md)*  
*Siguiente: [`03-infraestructura-aws.md`](03-infraestructura-aws.md)*
