3 Anexo B
3.1 Arquitectura y despliegue de AdminG Systems
Eduardo Martínez
3.2 Proposito del anexo
Este anexo documenta la arquitectura de AdminG Systems y su despliegue en una VM Micro Ubuntu de Oracle Cloud Free Tier. Mientras el Chapter 2 define los requerimientos, este documento explica como se organizan los componentes para cumplirlos: frontend, backend, base de datos, seguridad, modulos de negocio, archivos estaticos, configuracion de entorno y publicacion.
La arquitectura actual combina FastAPI como backend, SQLAlchemy como capa ORM, Alembic para migraciones, Pydantic para validacion, routers modulares por dominio y un frontend distribuido desde frontend-dist. En desarrollo local se accede por http://localhost:8000/; en el despliegue mostrado se accede por la IP publica http://157.151.206.208. Esta dualidad es importante: permite validar cambios localmente y luego observar la misma experiencia en la VM. Se continua el proceso con dominio adming-systems.online y encriptado.
3.3 Arquitectura logica
AdminG usa una arquitectura por capas con separacion clara de responsabilidades. La capa de presentacion renderiza las vistas, administra la sesion del usuario y consume la API. La capa de aplicacion recibe solicitudes HTTP, valida tokens, aplica reglas de plan y ejecuta casos de uso. La capa de persistencia guarda usuarios, clientes, citas, pagos, inventario, facturas, documentos y reglas comerciales.
Los routers principales incluyen autenticacion, usuarios, clientes, mascotas, negocio, citas, servicios, planes, inventario, pagos, caja, facturas, notificaciones, documentos, autorizaciones, CRM, onboarding e identidad. Tambien existen routers opcionales para tesoreria, ensamble, proyectos, inventario JAC, estrategia, reportes, administracion, inteligencia artificial, operaciones y EOE, cargados por feature flags o disponibilidad de modulo.
3.4 Modulos operativos
Los módulos operativos soportan la gestión diaria del negocio, incluyendo atención de clientes, programación de servicios y control de inventario
3.5 Administración y control
Los componentes administrativos gestionan la autenticación, los usuarios, los planes contratados y las operaciones financieras de la plataforma.
3.6 Seguridad y control de acceso
La seguridad se implementa mediante autenticación basada en JWT, control de acceso mediante permisos, protección criptográfica de credenciales y configuración segura mediante variables de entorno.
3.7 Despliegue en Oracle Free Tier
El despliegue en Oracle Free Tier es adecuado para desarrollo en produccion controlada porque ofrece una VM siempre gratuita, acceso SSH, disco persistente y libertad para ejecutar FastAPI como proceso del sistema. Frente a plataformas serverless, esta opcion permite conservar SQLite temporalmente, servir el frontend estatico desde la misma aplicacion y controlar configuraciones de red, puertos, firewall y logs.
La VM debe considerarse un entorno productivo de baja escala, no un simple laboratorio. Por ello, aunque la captura muestre Not secure, el cierre tecnico debe incluir HTTPS, dominio, CORS restringido, variables de entorno reales, secretos robustos, bloqueo de endpoints administrativos de desarrollo y backups de app.db. Si el proyecto crece o se habilita multiusuario intensivo, la persistencia debe migrarse a PostgreSQL.
3.8 Arquitectura de despliegue
3.9 Ciclo de solicitud
3.10 Flujo de datos y persistencia
3.11 Decisiones arquitectonicas
Se eligio FastAPI por su rendimiento, tipado, documentacion automatica y compatibilidad con Pydantic. SQLAlchemy permite mantener independencia parcial frente al motor de base de datos y Alembic permite evolucionar esquemas. El frontend distribuido como archivos estaticos simplifica el despliegue inicial: la misma app sirve API y SPA, evitando configurar un servidor web adicional en la primera etapa.
La modularidad es el punto central. Cada dominio tiene router, schemas, modelos y reglas propias. Esto evita que autenticacion, inventario, pagos o CRM se mezclen en una unica capa dificil de mantener. Ademas, los routers opcionales permiten que el sistema crezca sin obligar a cargar todos los modulos siempre.
3.12 Conexiones documentales
La arquitectura responde a los requerimientos del Chapter 2, depende del modelo de datos descrito en el Chapter 4, debe verificarse con los criterios del Chapter 5 y se evidencia en la implementacion del Chapter 6. Cualquier cambio en despliegue, dominio, HTTPS, base de datos o proceso de arranque debe actualizar este anexo y reflejarse en los demas.