Estructura recomendada de proyecto Flask
Estructura recomendada de un proyecto Flask
¿Por qué es importante la estructura?
Cuando empiezas con Flask, todo suele estar en un solo archivo (app.py). Eso funciona al inicio, pero rápidamente se vuelve difícil de mantener.
Una buena estructura te permite:
Escalar tu aplicación
Mantener el código organizado
Facilitar mantenimiento y cambios
Trabajar en equipo
Estructura básica (para empezar)
/proyecto
│
├── app.py
├── /templates
├── /static
└── /venv
app.py → lógica principal
templates/ → archivos HTML (Jinja2)
static/ → CSS, JS, imágenes
venv/ → entorno virtual
Esta estructura sirve para proyectos pequeños.
Estructura recomendada (profesional)
Cuando tu proyecto crece, usa esta organización:
/proyecto
│
├── app/
│ ├── __init__.py
│ ├── routes/
│ │ ├── usuarios.py
│ │ └── auth.py
│ ├── models/
│ │ └── usuario.py
│ ├── templates/
│ ├── static/
│ └── db.py
│
├── config.py
├── run.py
└── requirements.txt
Explicación de cada parte
app/
Aquí vive toda tu aplicación.
init.py
Inicializa Flask:
from flask import Flask
def create_app():
app = Flask(__name__)
from .routes.usuarios import usuarios_bp
app.register_blueprint(usuarios_bp)
return app
routes/
Contiene las rutas separadas por módulos:
from flask import Blueprint
usuarios_bp = Blueprint("usuarios", __name__)
@usuarios_bp.route("/usuarios")
def usuarios():
return "Lista de usuarios"
models/
Define estructuras de datos (opcional si usas ORM):
class Usuario:
def __init__(self, nombre):
self.nombre = nombre
db.py
Maneja la conexión a la base de datos:
import pyodbc
def get_connection():
return pyodbc.connect(
'DRIVER={SQL Server};'
'SERVER=localhost;'
'DATABASE=mi_base_datos;'
'Trusted_Connection=yes;'
)
config.py
Configuraciones del proyecto:
class Config:
SECRET_KEY = "clave_secreta"
run.py
Archivo principal para ejecutar la app:
from app import create_app
app = create_app()
if __name__ == "__main__":
app.run(debug=True)
¿Qué son los Blueprints?
Los Blueprints permiten dividir la app en partes independientes:
Usuarios
Autenticación
API
Admin
Esto evita tener un archivo gigante con todo el código.
Buenas prácticas
Si quieres que tu proyecto sea serio:
Usa Blueprints desde temprano
Separa lógica (routes, db, models)
No pongas todo en app.py
Usa variables de entorno para credenciales
Mantén nombres claros y consistentes
Errores comunes
Tener todo en un solo archivo
No usar carpetas
Mezclar HTML con lógica compleja
No separar configuración
Código difícil de escalar
¿Cuándo cambiar a esta estructura?
Haz el cambio cuando:
Tu app tenga más de 5–6 rutas
Empieces a usar base de datos
Tengas múltiples páginas
El código ya se sienta desordenado
Si esperas demasiado, migrar será más difícil.
Conclusión
Una buena estructura no es un lujo, es una necesidad si quieres que tu proyecto crezca sin romperse.
Organizar bien desde el inicio te ahorra tiempo, errores y dolores de cabeza.
¿Por qué es importante la estructura?
Cuando empiezas con Flask, todo suele estar en un solo archivo (app.py). Eso funciona al inicio, pero rápidamente se vuelve difícil de mantener.
Una buena estructura te permite:
Escalar tu aplicación
Mantener el código organizado
Facilitar mantenimiento y cambios
Trabajar en equipo
Estructura básica (para empezar)
/proyecto
│
├── app.py
├── /templates
├── /static
└── /venv
app.py → lógica principal
templates/ → archivos HTML (Jinja2)
static/ → CSS, JS, imágenes
venv/ → entorno virtual
Esta estructura sirve para proyectos pequeños.
Estructura recomendada (profesional)
Cuando tu proyecto crece, usa esta organización:
/proyecto
│
├── app/
│ ├── __init__.py
│ ├── routes/
│ │ ├── usuarios.py
│ │ └── auth.py
│ ├── models/
│ │ └── usuario.py
│ ├── templates/
│ ├── static/
│ └── db.py
│
├── config.py
├── run.py
└── requirements.txt
Explicación de cada parte
app/
Aquí vive toda tu aplicación.
init.py
Inicializa Flask:
from flask import Flask
def create_app():
app = Flask(__name__)
from .routes.usuarios import usuarios_bp
app.register_blueprint(usuarios_bp)
return app
routes/
Contiene las rutas separadas por módulos:
from flask import Blueprint
usuarios_bp = Blueprint("usuarios", __name__)
@usuarios_bp.route("/usuarios")
def usuarios():
return "Lista de usuarios"
models/
Define estructuras de datos (opcional si usas ORM):
class Usuario:
def __init__(self, nombre):
self.nombre = nombre
db.py
Maneja la conexión a la base de datos:
import pyodbc
def get_connection():
return pyodbc.connect(
'DRIVER={SQL Server};'
'SERVER=localhost;'
'DATABASE=mi_base_datos;'
'Trusted_Connection=yes;'
)
config.py
Configuraciones del proyecto:
class Config:
SECRET_KEY = "clave_secreta"
run.py
Archivo principal para ejecutar la app:
from app import create_app
app = create_app()
if __name__ == "__main__":
app.run(debug=True)
¿Qué son los Blueprints?
Los Blueprints permiten dividir la app en partes independientes:
Usuarios
Autenticación
API
Admin
Esto evita tener un archivo gigante con todo el código.
Buenas prácticas
Si quieres que tu proyecto sea serio:
Usa Blueprints desde temprano
Separa lógica (routes, db, models)
No pongas todo en app.py
Usa variables de entorno para credenciales
Mantén nombres claros y consistentes
Errores comunes
Tener todo en un solo archivo
No usar carpetas
Mezclar HTML con lógica compleja
No separar configuración
Código difícil de escalar
¿Cuándo cambiar a esta estructura?
Haz el cambio cuando:
Tu app tenga más de 5–6 rutas
Empieces a usar base de datos
Tengas múltiples páginas
El código ya se sienta desordenado
Si esperas demasiado, migrar será más difícil.
Conclusión
Una buena estructura no es un lujo, es una necesidad si quieres que tu proyecto crezca sin romperse.
Organizar bien desde el inicio te ahorra tiempo, errores y dolores de cabeza.