Visión General de la Arquitectura¶

El Sistema A3 es una aplicación web monolítica desarrollada con Django, diseñada específicamente para A Terceros Inmobiliaria. Esta página proporciona una visión general de alto nivel de la arquitectura del sistema.

Arquitectura de Alto Nivel¶

graph TB
    subgraph "Cliente"
        Browser[Navegador Web]
        PWA[PWA / iOS App]
    end

    subgraph "Frontend"
        Static[Static Files / WhiteNoise]
        JS[JavaScript SPA<br/>Window Manager]
        Templates[Django Templates]
    end

    subgraph "Backend - Django 3.2"
        Views[Views / ViewSets]
        API[Django REST Framework]
        Models[Models / ORM]
        Services[Business Logic]
        Signals[Django Signals]
    end

    subgraph "Almacenamiento"
        PostgreSQL[(PostgreSQL 12.3+)]
        S3[AWS S3<br/>Media Files]
    end

    subgraph "Integraciones"
        SAP[SAP HANA API<br/>ASP.NET]
        Push[Web Push<br/>VAPID]
    end

    Browser --> Static
    Browser --> Templates
    Browser --> API
    PWA --> Push

    Templates --> Views
    JS --> API
    API --> Services
    Views --> Services
    Services --> Models
    Services --> SAP

    Models --> PostgreSQL
    Services --> S3
    Signals --> Push

    style Backend fill:#092e20,color:#fff
    style PostgreSQL fill:#336791,color:#fff
    style S3 fill:#FF9900,color:#fff

Patrón Arquitectónico¶

Monolito Modular¶

El Sistema A3 utiliza una arquitectura monolítica modular donde:

Monolítico: Todo el código está en un solo repositorio y se despliega como una unidad
Modular: Organizado en múltiples Django apps, cada una con responsabilidades específicas

Ventajas de este Enfoque¶

✅ Simplicidad: Un solo codebase, un solo deployment ✅ Desarrollo rápido: No hay overhead de comunicación entre servicios ✅ Transacciones: ACID garantizado entre módulos ✅ Facilidad de testing: Todo el sistema se prueba junto

Capas de la Aplicación¶

1. Capa de Presentación¶

Tecnologías: Django Templates + JavaScript (jQuery) + Bootstrap

Templates HTML renderizados por Django
Sistema de "ventanas" simulando SPA
AJAX para interacciones sin recarga
Bootstrap para UI responsive

Ubicación: templates/, static/js/, static/css/

2. Capa de API¶

Tecnologías: Django REST Framework

API RESTful para el frontend
Serializers para validación de datos
ViewSets para operaciones CRUD
Autenticación basada en sesiones
Swagger/OpenAPI docs con drf-yasg

Ubicación: api/, */serializers.py, */viewsets.py

3. Capa de Lógica de Negocio¶

Tecnologías: Python + Django

Views (función y clase)
Servicios de negocio
Validaciones complejas
Integraciones externas
Procesamiento de archivos

Ubicación: */views.py, */utils.py, services/

4. Capa de Datos¶

Tecnologías: Django ORM + PostgreSQL

Modelos Django (ORM)
Migraciones automáticas
Queries optimizadas
Transacciones ACID
Relaciones complejas (ManyToMany, ForeignKey)

Ubicación: */models.py

5. Capa de Integración¶

Tecnologías: Requests + Boto3 + pywebpush

Cliente HTTP para SAP API
SDK de AWS para S3
Web Push para notificaciones
APIs externas

Ubicación: services/, */utils.py

Módulos Principales¶

El sistema está dividido en ~20 apps Django:

graph LR
    A[a3ceros<br/>Core] --> B[users<br/>Usuarios]
    A --> C[inventario<br/>Propiedades]
    A --> D[apartados<br/>Ventas]
    A --> E[clientes<br/>Clientes]
    A --> F[tickets<br/>Tickets/Tareas]
    A --> G[comprobaciones<br/>Gastos]
    A --> H[ch<br/>RRHH]
    A --> I[anexos<br/>Archivos]
    A --> J[dashboard<br/>Analytics]
    A --> K[reportes<br/>Informes]

    style A fill:#092e20,color:#fff

Ver detalles de cada módulo en la sección de Módulos.

Flujo de Datos¶

Flujo Típico de una Petición¶

sequenceDiagram
    participant U as Usuario
    participant F as Frontend (JS)
    participant V as View/API
    participant S as Service
    participant M as Model
    participant DB as PostgreSQL
    participant E as SAP API

    U->>F: Acción (click, submit)
    F->>V: HTTP Request (AJAX)
    V->>S: Llamada a servicio
    S->>M: Query ORM
    M->>DB: SQL Query
    DB-->>M: Resultados
    S->>E: API Request (si necesario)
    E-->>S: Respuesta
    S-->>V: Datos procesados
    V-->>F: JSON Response
    F-->>U: UI Update

Ejemplo Concreto: Crear un Cliente¶

Usuario llena formulario en el navegador
JavaScript valida datos y envía AJAX POST
View/API recibe la petición
Serializer valida los datos
Service procesa la lógica:
Crea el cliente en PostgreSQL
Envía datos a SAP API
Sube archivos adjuntos a S3
Response regresa al frontend
UI se actualiza con el nuevo cliente

Patrones de Diseño Utilizados¶

Repository Pattern¶

Separación entre lógica de negocio y acceso a datos:

# services/cliente_service.py
class ClienteService:
    def crear_cliente(self, data):
        # Validación
        # Lógica de negocio
        # Llamadas a API externa
        # Persistencia
        pass

Signal-Observer Pattern¶

Django Signals para desacoplar eventos:

# Cuando se crea un apartado, notificar
@receiver(post_save, sender=Apartado)
def notificar_apartado_creado(sender, instance, created, **kwargs):
    if created:
        notificar_usuarios(instance)

Factory Pattern¶

Para creación de objetos complejos (reportes, anexos):

class ReporteFactory:
    @staticmethod
    def crear_reporte(tipo, params):
        if tipo == 'ventas':
            return ReporteVentas(params)
        elif tipo == 'inventario':
            return ReporteInventario(params)

Seguridad¶

Autenticación y Autorización¶

Autenticación: Django session-based auth
Autorización: Django Groups & Permissions
9 Grupos: Beta, Contabilidad, Coordinador, Corporativo, Gerente, Marketing, RC, Sistemas, Tesorería
Multi-tenancy: Filtrado por Plaza

Protecciones Implementadas¶

✅ CSRF Protection (Django middleware) ✅ SQL Injection (ORM parametrizado) ✅ XSS Protection (template escaping) ✅ Clickjacking Protection (X-Frame-Options) ✅ SSL/TLS en producción (Heroku) ✅ Secrets en variables de entorno

Escalabilidad¶

Estrategias Actuales¶

Horizontal: Múltiples dynos en Heroku
Base de Datos: PostgreSQL con índices optimizados
Caché: Django cache framework
Static Files: WhiteNoise + CDN
Media Files: AWS S3 con CloudFront
Queries: Prefetch y select_related

Puntos de Mejora Futura¶

Implementar Redis para caché distribuido
Separar tareas pesadas a Celery
Implementar read replicas de PostgreSQL
Migrar a microservicios (si el negocio crece)

Performance¶

Métricas Actuales (Estimadas)¶

Response Time: ~200-500ms (promedio)
Database Queries: 5-20 por request (optimizable)
Static Assets: Servidos con compresión gzip/brotli
Uptime: 99.9% (Heroku SLA)

Optimizaciones Implementadas¶

WhiteNoise para static files
Django Debug Toolbar (solo desarrollo)
Select related / Prefetch related
Índices en campos frecuentes
Compresión de imágenes antes de subir
Paginación en listados

Monitoreo y Logs¶

Logs: Heroku logs (stdout/stderr)
Errores: Django error reporting
Métricas: Heroku metrics
APM: (Considerar New Relic o Datadog)

Próximas Secciones¶

Para entender mejor la arquitectura, continúa con:

Stack Tecnológico: Detalle de todas las tecnologías
Frontend: Arquitectura del cliente
Backend: Estructura de apps Django
Base de Datos: Esquema y relaciones
Integraciones: APIs externas

Esta arquitectura ha evolucionado con el negocio y continuará adaptándose a las necesidades de A Terceros Inmobiliaria.