Backend · BLANK Intranet

¿Qué es esto?

El cerebro de BLANK. 8 servicios pequeños, cada uno con una sola responsabilidad, hablando entre sí a través de un gateway Traefik.

Cada servicio tiene su propia base de datos lógica en Postgres, sus endpoints REST, sus migraciones de Alembic, y su capa de negocio. Casi toda la lógica real está aún por escribir: los modelos y esquemas existen, los endpoints son plantillas.

Empieza por auth-service y device-service: son los dos que necesita el teléfono para funcionar.

Stack técnico

Python 3.12
FastAPI + Uvicorn
SQLAlchemy 2.0 (asíncrono)
Pydantic v2 (schemas y validación)
Alembic (migraciones)
PostgreSQL 16 + Redis 7
Traefik (gateway)
pytest + httpx (tests)

Estructura de carpetas

backend/
├── gateway/                 Traefik config
├── shared/blank_shared/     utils comunes (auth, errors, logging)
│   └── capabilities/        matriz de capacidades compartida (fuente de verdad)
├── auth-service/            puerto 8000  — login, JWT, usuarios
├── device-service/          puerto 8001  — registro, heartbeat + enrollment/capabilities
├── policy-service/          puerto 8002  — reglas de uso, horarios + compatibility
├── family-service/          puerto 8003  — grupos familiares
├── usage-service/           puerto 8004  — tracking de tiempo por app
├── billing-service/         puerto 8005  — Stripe, facturas, suscripciones
├── notification-service/    puerto 8006  — ntfy push + email
└── content-filter-service/  puerto 8007  — categorías y filtros
Cada servicio sigue el mismo layout:
  app/
    main.py          FastAPI app
    api/v1/          routers (incluye capabilities/, enrollment/, compatibility/)
    models/          SQLAlchemy
    schemas/         Pydantic
    services/        lógica de negocio
    migrations/      Alembic

Archivos clave

Archivo	Qué hace	Prioridad
auth-service/app/api/v1/auth.py	Endpoints de login, register, refresh.	Alta
auth-service/app/services/jwt.py	Emisión y validación de tokens.	Alta
device-service/app/api/v1/devices.py	Registro y heartbeat de teléfonos.	Alta
policy-service/app/services/policy_engine.py	Evalúa qué está permitido y cuándo.	Alta
family-service/app/models/family.py	Modelo de familia + miembros.	Media
usage-service/app/api/v1/usage.py	Ingesta de eventos de uso desde los teléfonos.	Media
billing-service/app/services/stripe_client.py	Integración con Stripe.	Media
notification-service/app/services/ntfy.py	Push a teléfonos vía ntfy.	Media
content-filter-service/app/data/categories.py	Catálogo de categorías de apps.	Baja
shared/blank_shared/auth.py	Dependencia FastAPI para validar JWT.	Alta
shared/blank_shared/capabilities/capability_matrix.py	Fuente de verdad compartida de capacidades por modo.	Alta
device-service/app/services/enrollment_classifier.py	Clasifica el device en registro (COMPANY_DO / BYOD_FULL_DO / BYOD_LIMITED).	Alta
policy-service/app/services/policy_compatibility_service.py	Valida políticas contra capacidades del device.	Alta

Cómo ejecutarlo

Arrancar postgres, redis y el resto de infra

make docker-up

Aplicar migraciones de todos los servicios

make migrate

Arrancar auth-service en modo reload

cd backend/auth-service && uvicorn app.main:app --reload --port 8000

Arrancar device-service

cd backend/device-service && uvicorn app.main:app --reload --port 8001

Crear una migración nueva

cd backend/auth-service && alembic revision --autogenerate -m "descripcion"

Correr los tests de un servicio

cd backend/auth-service && pytest

Qué falta

0 de 25 completados

Alta Media Baja

Dependencias con otros módulos

Depende de Postgres, Redis y Traefik levantados (make docker-up).
El paquete blank_shared se instala en modo editable en todos los servicios.
billing-service necesita claves de Stripe en .env.