Este repositorio contiene un entorno de desarrollo completo con FastAPI para el backend y Vue para el frontend, orquestado mediante Docker Compose.
git clone https://github.com/jbastian9/Docker_Python.git
cd Docker_Python
docker-compose up --detach --build --remove-orphans
🗃️ Migraciones de Base de Datos
Una vez los contenedores estén corriendo, debes aplicar las migraciones de base de datos para crear las tablas necesarias en PostgreSQL.
📦 Ejecutar migraciones
docker exec -it <nombre_contenedor_app> bash
alembic upgrade head
✅ Esto aplicará todas las migraciones generadas con Alembic dentro del contenedor.
🚀 Estructura General del Proyecto
Esta es la estructura global del proyecto que integra tanto el backend como el frontend, manteniendo una separación clara entre ambos, pero asegurando que puedan interactuar de forma eficiente. La organización está pensada para facilitar la escalabilidad, la colaboración entre equipos y la buena práctica en la gestión de servicios.
📁 Estructura General del Proyecto
Aplicativo/
├── docker/ # Archivos necesarios para la contenedorización de Docker
│ └── Dockerfile_api # Dockerfile para el backend (API)
│ └── Dockerfile_vue # Dockerfile para el frontend (Vue.js)
├── docroot/ # Carpeta raíz para alojar los directorios del aplicativo
│ ├── app/ # Carpeta que contiene todo lo relacionado con el backend (FastAPI)
│ └── vue/ # Carpeta que contiene todo lo relacionado con el frontend (Vue.js)
├── .env # Archivo de variables de entorno (Configuraciones privadas)
├── .env.example # Ejemplo de archivo .env para desarrollo
├── .gitignore # Ignorar archivos y carpetas que no deben ser versionados
├── docker-compose.yml # Configuración de Docker Compose para la infraestructura completa
└── README.md
🧩 Convenciones y Recomendaciones
📦 Contenedores Docker
Los archivos Dockerfile_api y Dockerfile_vue son utilizados para contenerizar el backend y frontend, respectivamente. Asegúrate de construir y correr cada uno por separado según el entorno que necesites.
Dockerfile_api: Contiene la configuración para el backend, usando Python, FastAPI, y otros servicios backend.
Dockerfile_vue: Contiene la configuración para el frontend, utilizando Node.js, Vue.js, y Vuetify.
📁 Carpeta app
Contiene todo el código relacionado con el backend utilizando FastAPI. Aquí se encuentran las configuraciones del servidor, los endpoints de la API, la base de datos (SQLAlchemy + Alembic) y las configuraciones de tareas en segundo plano (Celery).
Se recomienda estructurar la carpeta en diferentes módulos como auth, user, product, etc., para tener un control adecuado sobre la funcionalidad y escalabilidad.
📁 Carpeta vue
Contiene todo el código relacionado con el frontend utilizando Vue.js 3 + Vuetify. Aquí se encuentran los componentes, las vistas, los servicios, el enrutamiento y el estado global de la aplicación.
La estructura interna de esta carpeta debe seguir buenas prácticas para garantizar un código mantenible y escalable.
🌍 Configuración de Entornos
El archivo .env es donde se deben colocar todas las variables de entorno para el proyecto. Utiliza .env.example como referencia para las variables necesarias en los entornos de desarrollo y producción.
🚫 .gitignore
Asegúrate de ignorar archivos y directorios que no deban ser versionados, como las carpetas node_modules/, pycache/, o archivos locales de configuración del entorno.
🧑💻 Docker Compose
El archivo docker-compose.yml permite levantar tanto el backend como el frontend en contenedores de manera fácil, gestionando las dependencias de ambos entornos, como la base de datos y los servicios adicionales.
---
# ⚙️ Backend FastAPI – Estructura de Proyecto
Este proyecto implementa un backend moderno utilizando **FastAPI**, con soporte para tareas asincrónicas, WebSockets, seguridad robusta y una base de datos relacional conectada a través de SQLAlchemy. Está diseñado para ser **modular, escalable, reutilizable y limpio**.
---
## 📁 Estructura del Proyecto
```bash
app/
├── alembic/ # Configuración y plantillas de migraciones con Alembic
│ ├── versions/ # Migraciones autogeneradas (no editar manualmente)
│ ├── env.py # Configuración de entorno de migraciones
│ ├── README # Archivo auxiliar de Alembic
│ └── script.py.mako # Plantilla para nuevas migraciones
│
├── api/ # Endpoints del sistema
│ ├── __init__.py # Requerido para que sea un paquete Python
│ └── usuario.py # Módulo de rutas relacionadas con usuarios
│
├── core/ # Configuración base de la aplicación
│ ├── __init__.py
│ └── configuracion.py # Carga y gestión de variables de entorno, settings globales
│
├── db/ # Lógica de base de datos
│ ├── __init__.py
│ ├── base.py # Declaración base de modelos
│ ├── session.py # Configuración de conexión y sesión con la BD
│ └── modelos/ # Modelos ORM separados por dominio
│ ├── __init__.py
│ └── usuario.py # Modelo SQLAlchemy para usuarios
│
├── esquemas/ # Esquemas Pydantic para validación y serialización
│ ├── __init__.py
│ └── usuario.py # Schemas para creación, actualización, salida de usuarios
│
├── servicios/ # Lógica de negocio y conexión entre BD y endpoints
│ ├── __init__.py
│ └── usuario.py # Lógica para gestión de usuarios
│
├── tareas/ # Tareas en segundo plano con Celery
│ ├── __init__.py
│ └── correos.py # Envío de correos electrónicos asincrónicos
│
├── sockets/ # Comunicación en tiempo real con WebSockets
│ ├── __init__.py
│ └── notificaciones.py # Canal de notificaciones vía WebSocket
│
├── static/ # Archivos estáticos servidos por FastAPI (si aplica)
├── uploads/ # Archivos subidos por el usuario (PDFs, imágenes, etc.)
│
├── main.py # Punto de entrada principal de la aplicación
├── alembic.ini # Configuración global de Alembic
├── requirements.txt # Dependencias del backend
🧩 Convenciones y Recomendaciones
📄 Nomenclatura de Archivos
Se debe usar español siempre que sea posible: usuario.py, esquemas/, servicios/, configuracion.py.
Los archivos deben usar snake_case (nombre_archivo.py).
Los esquemas deben reflejar claramente su propósito: UsuarioCrear, UsuarioRespuesta, etc.
📦 Paquetes Python (__init__.py)
Cada carpeta que actúe como módulo o paquete debe contener un archivo __init__.py.
Aunque en Python moderno no siempre es obligatorio, se recomienda para mantener consistencia y facilitar importaciones claras.
🔄 Migraciones
🛠 Alembic
Las migraciones generadas automáticamente se almacenan en alembic/versions/.
No se debe modificar manualmente el contenido de versions/.
Para crear nuevas migraciones:
alembic revision --autogenerate -m "descripcion_del_cambio"
alembic upgrade head
🛠 Requisitos Técnicos Cubiertos
✅ FastAPI
✅ SQLAlchemy 2.0 + Alembic
✅ Pydantic
✅ JWT / OAuth2
✅ WebSockets
✅ Celery + Redis
✅ aiosmtplib / yagmail
✅ Pytest + HTTPX
✅ Pre-commit + Black + Isort + Flake8
✅ Sphinx / MkDocs
📚 Consejos de Organización
Los módulos deben estar separados por dominio (usuario, auth, notificacion, etc.).
No mezcles rutas, lógica de negocio y validaciones en un solo archivo.
Centraliza configuraciones en core/configuracion.py.
Usa nombres expresivos y consistentes, todo en español donde tenga sentido.
---
# 🎨 Proyecto Frontend Vue 3 + Vuetify
Este proyecto es la implementación del frontend del sistema, construido con **Vue 3 (Composition API)**, **Vuetify 3**, **Pinia**, **Vue Router** y otras herramientas modernas. La estructura está diseñada para ser **escalable, mantenible y reutilizable**, siguiendo buenas prácticas y estándares profesionales.
## 📁 Estructura del Proyecto
```bash
vue/
├── public/
│ └── index.html # Archivo HTML principal; punto de entrada al frontend.
├── src/
│ ├── assets/ # Archivos estáticos como imágenes, fuentes e íconos.
│ │ └── logo.png # Ejemplo de recurso gráfico usado en la app.
│
│ ├── components/ # Componentes globales reutilizables en distintas vistas.
│ │ └── base/ # Componentes UI atómicos: botones, inputs, selectores.
│ │ └── layout/ # Componentes estructurales como Header, Sidebar, Footer.
│
│ ├── composables/ # Funciones reutilizables con Composition API.
│ │ └── useAuth.js # Ejemplo: lógica de autenticación centralizada.
│
│ ├── layouts/ # Layouts base reutilizables para distintas secciones.
│ │ └── DefaultLayout.vue # Layout principal (usuarios autenticados).
│ │ └── AuthLayout.vue # Layout para páginas públicas o de autenticación.
│
│ ├── router/ # Configuración de rutas con Vue Router.
│ │ └── index.js # Definición de rutas principales y carga perezosa.
│
│ ├── services/ # Lógica de acceso a APIs con Axios.
│ │ └── http.js # Configuración base de Axios (URL, headers, interceptores).
│ │ └── usuarioService.js # Ejemplo de servicio: operaciones CRUD del módulo usuario.
│
│ ├── store/ # Gestión de estado global usando Pinia.
│ │ └── usuarioStore.js # Ejemplo: almacenamiento del estado de usuario.
│
│ ├── styles/ # Estilos globales del sistema.
│ │ └── variables.scss # Variables de diseño: colores, fuentes, tamaños, etc.
│ │ └── global.scss # Estilos globales compartidos en toda la app.
│
│ ├── utils/ # Funciones utilitarias reutilizables.
│ │ └── formatFecha.js # Ejemplo: formateo de fechas para mostrar al usuario.
│
│ ├── views/ # Vistas o páginas del sistema, categorizadas por módulo.
│ │ └── usuario/ # Módulo "usuario": autenticación, registro, perfil, etc.
│ │ └── Ingreso.vue # Vista para iniciar sesión (login).
│ │ └── Registro.vue # Vista para crear una nueva cuenta.
│ │ └── dashboard/ # Módulo "dashboard": resumen, gráficas, widgets.
│ │ └── Inicio.vue # Página principal del dashboard al iniciar sesión.
│
│ ├── App.vue # Componente raíz: estructura inicial del proyecto.
│ └── main.js # Archivo principal que monta la app y configura plugins.
│
├── tests/ # Pruebas automatizadas.
│ ├── unit/ # Pruebas unitarias con Vitest.
│ └── e2e/ # Pruebas end-to-end con Cypress.
│
├── .eslintrc.cjs # Configuración del linter ESLint.
├── .prettierrc # Configuración del formateador de código Prettier.
├── vite.config.js # Configuración de Vite como empaquetador.
└── package.json # Dependencias y scripts del proyecto.
🧩 Convenciones y recomendaciones para desarrollo
📦 Subcarpetas por módulo
Para mantener la escalabilidad del proyecto, toda funcionalidad o módulo debe tener su propio espacio en las siguientes carpetas:
views/
Organiza las vistas en carpetas por módulo:
├── views/
│ ├── usuario/
│ │ └── Ingreso.vue
│ │ └── Registro.vue
│ ├── producto/
│ │ └── Listado.vue
│ │ └── Detalle.vue
- Usar nombres en español (Ingreso.vue, Registro.vue).
- Nombres claros y representativos de la funcionalidad.
services/
Agrupar los servicios en subcarpetas por módulo:
├── services/
│ ├── http.js # Configuración general de Axios
│ ├── usuario/
│ │ └── index.js # Servicio de API para usuarios
│ ├── producto/
│ │ └── index.js # Servicio de API para productos
store/
Los archivos separados o subcarpetas según la complejidad:
├── store/
│ ├── index.js # Configuración base de Pinia
│ ├── usuario/
│ │ └── usuarioStore.js
│ ├── producto/
│ │ └── productoStore.js
🧠 Reglas de nomenclatura
- Carpetas en minúsculas, separadas por guiones si es necesario (usuario, configuracion-general).
- Vistas en español, usando PascalCase en .vue (Ingreso.vue, Inicio.vue).
- Componentes base reutilizables en inglés si son genéricos (BaseButton.vue, BaseInput.vue), pero los específicos del negocio deben estar en español (TarjetaUsuario.vue).
🧪 Pruebas
- Las pruebas unitarias se escriben en tests/unit/ usando Vitest.
- Las pruebas e2e se manejan en tests/e2e/ usando Cypress.
🎨 Personalización dinámica (próximamente)
La app está preparada para una futura personalización dinámica:
- Paleta de colores, tipografías y componentes podrán definirse desde base de datos.
- Los estilos se centralizan en styles/variables.scss para facilitar su parametrización.