CuidApp 🐾 — Plataforma de Adopción y Apadrinamiento de Mascotas

Plataforma backend diseñada para conectar refugios y centros de adopción de mascotas con adoptantes, padrinos, hogares temporales y donantes en Chile.

Este proyecto cumple estrictamente con el marco regulatorio chileno vigente sobre tenencia responsable y protección de datos personales.

---

⚖️ Marco Legal Chileno (Cumplimiento)

• Ley 21.020 (Ley Cholito — Tenencia Responsable):
  • Registro e identificación obligatoria por microchip de 15 dígitos (ISO 11784).
  • Tenedores responsables identificados formalmente mediante su RUT.
  • Registro de declaratorias de Perros Potencialmente Peligrosos (PPP).
  • Fomento de la esterilización y trazabilidad sanitaria (vacunas como antirrábica y séxtuple).
• Ley 21.719 (Protección de Datos Personales):
  • Consentimiento granular: Cada consentimiento (marketing, matching, geolocalización) se registra de forma libre, específica, informada y revocable en la tabla consentimiento, conservando histórico y evidencias hash SHA-256.
  • Derechos ARCO: Gestión interna de solicitudes de Acceso, Rectificación, Cancelación y Oposición a través de la tabla solicitud_titular.

---

🛠️ Arquitectura y Stack Tecnológico

El backend se compone de dos servicios principales empaquetados mediante Docker Compose:

• Base de Datos: PostgreSQL 16 (Alpine-based).
• API Service: Python 3.12 + FastAPI + SQLAlchemy 2.0 (Async mapping) + Pydantic v2 + JWT & Argon2id.

🐳 Topología de Contenedores Docker (Para TI/DevOps)

El proyecto está configurado bajo el nombre de proyecto Compose cuidapp para facilitar la identificación y el control por parte de cualquier administrador de sistemas (TI).

Servicio Compose	Nombre del Contenedor	Imagen Docker	Puerto Expuesto	Volumen / Persistencia
db	cuidapp-db	postgres:16-alpine	5432:5432	cuidapp_pgdata (datos del motor PostgreSQL)
api	cuidapp-api	cuidapp-api:latest	8000:8000	Montaje del directorio local en /app (hot-reload)

---

🚀 Guía de Inicio Rápido

1. Requisitos

• Docker y Docker Compose V2 instalados y corriendo.
• Puerto 5432 y 8000 libres en el host.

2. Levantar los servicios

Navega a la carpeta del backend y levanta la topología en segundo plano:

cd backend
docker-compose up -d --build

3. Poblar la Base de Datos (Seed Data)

Pobla la base de datos con datos de prueba realistas chilenos (usuarios, centros de adopción reales, mascotas pre-cargadas, vacunas y consentimientos) ejecutando el script dentro del contenedor de la API:

docker-compose exec api python seed.py

4. Verificar funcionamiento

• Health Check: http://localhost:8000/health
• Documentación Interactiva (Swagger UI): http://localhost:8000/docs
• Documentación Alternativa (ReDoc): http://localhost:8000/redoc

---

📂 Estructura del Proyecto

Cuidapp/
├── db/
│   └── migrations/           # Scripts SQL de inicialización y migración
├── backend/
│   ├── app/
│   │   ├── models/           # Modelos de SQLAlchemy 2.0
│   │   ├── schemas/          # Schemas de validación Pydantic
│   │   ├── routers/          # Endpoints de la API FastAPI
│   │   ├── utils/            # Validadores chilenos (RUT módulo 11, etc.)
│   │   ├── config.py         # Configuración del entorno
│   │   ├── database.py       # Sesión asíncrona SQLAlchemy
│   │   └── security.py       # Hashing Argon2id y tokens JWT
│   ├── Dockerfile            # Construcción de la imagen cuidapp-api
│   ├── docker-compose.yml    # Orquestación db y api
│   ├── seed.py               # Script para poblar la DB con datos de prueba
│   └── pyproject.toml        # Dependencias de Python (uv)
└── CLAUDE.md                 # Fuente de verdad interna para desarrollo

---

⌨️ Comandos Útiles para Administración (TI)

• Ver logs de la API en tiempo real:

  docker-compose logs -f api

• Detener la plataforma:

  docker-compose down

• Limpiar y reiniciar base de datos (Volumen incluido):

  docker-compose down -v
  docker-compose up -d
  docker-compose exec api python seed.py