Skip to content

Brayan1262/taskguard-fastapi

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

10 Commits
app
app
 
 
tests
tests
 
 
.env.example
.env.example
 
 
.gitignore
.gitignore
 
 
README.md
README.md
 
 
docker-compose.yml
docker-compose.yml
 
 
requirements.txt
requirements.txt
 
 

Repository files navigation

TaskGuard API

Python FastAPI PostgreSQL Docker JWT Pytest

API REST profesional para gestión de proyectos y tareas, con autenticación JWT, RBAC, PostgreSQL, Docker, logging, manejo global de errores, dashboard de métricas y tests automatizados.

Descripción

TaskGuard API es un backend moderno construido con Python y FastAPI, diseñado para demostrar buenas prácticas en arquitectura por capas, seguridad, observabilidad básica y calidad de software.

El sistema permite registrar usuarios, autenticarse con JWT, gestionar proyectos y tareas con permisos por rol, consultar métricas en un dashboard y exponer documentación interactiva con Swagger/OpenAPI.

Tecnologías utilizadas

Categoría Tecnología
Lenguaje Python 3.12
Framework FastAPI
Base de datos PostgreSQL
ORM SQLAlchemy
Validación Pydantic
Configuración Pydantic Settings
Contenedores Docker, Docker Compose
Autenticación JWT (python-jose)
Seguridad Passlib, Bcrypt
Testing Pytest, Pytest-cov, httpx
Observabilidad Logging, middleware HTTP
Documentación OpenAPI / Swagger

Características principales

  • Registro de usuarios
  • Login con JWT
  • Usuario autenticado (GET /api/auth/me)
  • Roles ADMIN, MANAGER y DEVELOPER
  • RBAC (control de acceso basado en roles)
  • CRUD de proyectos
  • CRUD de tareas
  • Asignación de tareas a usuarios
  • Estados y prioridades de tareas
  • Dashboard de métricas (personal y general)
  • Manejo global de errores en formato JSON
  • Logging de requests
  • Middleware con header X-Process-Time
  • Tests automatizados con pytest
  • Documentación Swagger en /docs

Arquitectura del proyecto

app/
├── api/              # Routers y endpoints HTTP
├── core/             # Config, seguridad, dependencias, middleware
├── db/               # Conexión SQLAlchemy e inicialización
├── exceptions/       # Handlers globales de errores
├── models/           # Modelos ORM y enums
├── repositories/     # Acceso a datos
├── schemas/          # Esquemas Pydantic (request/response)
├── services/         # Lógica de negocio
├── utils/            # Utilidades
└── main.py           # Punto de entrada FastAPI

tests/
├── conftest.py
├── test_auth.py
├── test_dashboard.py
├── test_health.py
├── test_projects.py
├── test_protected.py
└── test_tasks.py

Roles del sistema

ADMIN

  • Puede administrar todos los proyectos y tareas.
  • Puede ver el dashboard general (/api/dashboard/summary).
  • Puede eliminar cualquier proyecto.

MANAGER

  • Puede ver y gestionar proyectos/tareas con permisos superiores.
  • Puede ver el dashboard general.
  • Puede eliminar solo proyectos propios.

DEVELOPER

  • Puede crear proyectos propios.
  • Puede gestionar sus tareas y proyectos permitidos.
  • No puede listar todos los proyectos/tareas del sistema.
  • No puede acceder a recursos administrativos ni al dashboard general.

Cómo ejecutar el proyecto

1. Clonar el repositorio

git clone https://github.com/Brayan1262/taskguard-fastapi.git
cd taskguard-fastapi

2. Crear entorno virtual

python -m venv venv

Windows (CMD):

venv\Scripts\activate

Linux / macOS:

source venv/bin/activate

3. Instalar dependencias

pip install -r requirements.txt

4. Configurar variables de entorno

Copia .env.example a .env y ajusta los valores si es necesario:

APP_NAME=TaskGuard API
APP_VERSION=1.0.0
APP_ENV=development
DATABASE_URL=postgresql://postgres:postgres@localhost:5435/taskguard_db
JWT_SECRET_KEY=taskguard-super-secret-key
JWT_ALGORITHM=HS256
JWT_ACCESS_TOKEN_EXPIRE_MINUTES=1440

Nota: El archivo .env no se sube a GitHub por seguridad. Usa .env.example como plantilla.

5. Levantar PostgreSQL con Docker

docker compose up -d

6. Ejecutar la API

uvicorn app.main:app --reload

La API estará disponible en: http://127.0.0.1:8000

Docker

Levantar PostgreSQL:

docker compose up -d

Verificar contenedor:

docker ps
Servicio Contenedor Puerto
PostgreSQL taskguard_postgres 5435 → 5432

Swagger / OpenAPI

Documentación interactiva:

http://127.0.0.1:8000/docs

Para endpoints protegidos, haz login en POST /api/auth/login, copia el access_token y en Authorize pega:

Bearer TU_TOKEN_AQUI

Endpoints principales

Método Endpoint Descripción
GET / Health básico de la API
GET /api/test Endpoint de prueba
GET /api/health/db Estado de conexión a BD
GET /api/health/tables Verificación de tablas
POST /api/auth/register Registro de usuario
POST /api/auth/login Login y obtención de JWT
GET /api/auth/me Perfil del usuario autenticado
GET /api/protected/* Rutas protegidas por rol
CRUD /api/projects Gestión de proyectos
CRUD /api/tasks Gestión de tareas
GET /api/dashboard/me Dashboard personal
GET /api/dashboard/summary Dashboard general (ADMIN/MANAGER)

Ejemplos de uso con curl

Registro

curl -X POST "http://127.0.0.1:8000/api/auth/register" \
  -H "Content-Type: application/json" \
  -d "{\"first_name\":\"Brayan\",\"last_name\":\"Chavez\",\"email\":\"brayan@gmail.com\",\"password\":\"12345678\"}"

Login

curl -X POST "http://127.0.0.1:8000/api/auth/login" \
  -H "Content-Type: application/json" \
  -d "{\"email\":\"brayan@gmail.com\",\"password\":\"12345678\"}"

Crear proyecto (con token)

curl -X POST "http://127.0.0.1:8000/api/projects" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"name\":\"Sistema Interno\",\"description\":\"Proyecto backend\",\"status\":\"ACTIVE\"}"

Crear tarea (con token)

curl -X POST "http://127.0.0.1:8000/api/tasks" \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"title\":\"Implementar módulo\",\"description\":\"CRUD de tareas\",\"status\":\"TODO\",\"priority\":\"HIGH\",\"project_id\":1}"

Dashboard personal

curl -X GET "http://127.0.0.1:8000/api/dashboard/me" \
  -H "Authorization: Bearer TOKEN"

Testing

Asegúrate de tener PostgreSQL corriendo (docker compose up -d) y el entorno virtual activado.

pytest

Con cobertura:

pytest --cov=app

Los tests usan emails únicos (UUID) para evitar conflictos en la base de datos local.

Estado del proyecto

Versión 1.0 — Funcional

Módulos completados:

  1. Setup FastAPI y estructura profesional
  2. PostgreSQL + Docker + SQLAlchemy
  3. Modelos y relaciones
  4. Autenticación JWT
  5. Usuario autenticado + RBAC
  6. CRUD de proyectos
  7. CRUD de tareas
  8. Dashboard de métricas
  9. Manejo global de errores + logging
  10. Tests con pytest
  11. README profesional + GitHub

Futuras mejoras

  • Refresh token
  • Recuperación de contraseña
  • Integración con servicios externos
  • Retries y circuit breaker
  • Observabilidad avanzada
  • Cloud Logging / Cloud Trace
  • Deploy en GCP
  • CI/CD con GitHub Actions

Autor

Brayan Jair Chavez Oscor

Licencia

Este proyecto fue desarrollado con fines educativos y de portafolio profesional.

About

Professional FastAPI REST API with JWT, RBAC, PostgreSQL, Docker, logging, dashboard metrics and pytest.

brayan1262.github.io/portafolio-brayan/

Topics

python docker sqlalchemy jwt backend logging postgresql openapi pytest rbac api-rest pydantic fastapi

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages