Location Management System

Demo publicada: https://sucursales.kevincarcache.com/

Location Management System es una demo MVP full-stack creada para resolver un problema frecuente en negocios con presencia fisica: administrar, mantener y publicar ubicaciones comerciales desde una unica fuente de verdad.

El proyecto simula una plataforma donde un equipo interno puede gestionar localizaciones, mientras los usuarios finales consultan esa informacion desde una experiencia publica moderna, clara y apoyada en un mapa interactivo.

Problema

Muchas empresas que operan con sucursales, oficinas, tiendas, centros de servicio o puntos de atencion terminan administrando la informacion de sus ubicaciones de forma fragmentada.

Direcciones, coordenadas, horarios, estados de publicacion, datos de contacto y detalles operativos pueden quedar distribuidos entre hojas de calculo, documentos internos, sistemas administrativos separados y cambios manuales en paginas web. Esa dispersion genera datos desactualizados, errores operativos, dificultad para escalar y friccion para usuarios que solo quieren encontrar el punto correcto.

El reto no era solo mostrar una direccion en un mapa. La necesidad real estaba en disenar un flujo confiable para capturar, administrar, validar y publicar informacion geografica de forma consistente.

Solucion

El MVP propone una plataforma centralizada que conecta la administracion interna con la experiencia publica.

El sistema se compone de tres piezas principales:

• Backend API: expone contratos, gestiona logica de negocio, autenticacion, persistencia y migraciones.
• Panel administrativo: permite al equipo interno administrar ubicaciones desde una interfaz privada.
• Storefront publico: presenta las ubicaciones a usuarios finales mediante una web con mapa interactivo.

La idea central es simple: el equipo administra las ubicaciones una sola vez y el publico consulta informacion consistente, actualizada y facil de explorar.

Que permite hacer

El proyecto esta pensado como base funcional para gestion de sucursales comerciales, publicacion de puntos de atencion, administracion de oficinas regionales, catalogos de tiendas o distribuidores y directorios de ubicaciones con experiencia de mapa.

Como demo MVP, demuestra el ciclo principal del producto:

• Registrar y mantener ubicaciones.
• Persistir informacion en una base de datos.
• Proteger la administracion mediante autenticacion.
• Compartir contratos entre backend y frontend.
• Publicar datos en una web publica.
• Visualizar ubicaciones en una interfaz geografica.

Arquitectura

El sistema esta organizado como un monorepo para mantener juntas las aplicaciones y paquetes compartidos del producto.

• apps/api: backend construido con FastAPI, encargado de autenticacion, modelos de datos, migraciones, seeds, logica de negocio e importaciones.
• apps/admin: panel interno construido con Vue 3 y Vuetify para la operacion administrativa.
• apps/web: storefront publico construido con Nuxt, Vuetify y MapLibre para la consulta visual de ubicaciones.
• packages/types: contratos TypeScript compartidos para mantener alineados los datos entre aplicaciones.
• packages/ui: tokens visuales ligeros para consistencia de interfaz.
• packages/config: configuracion TypeScript reutilizable dentro del monorepo.

Stack tecnico

• FastAPI
• Python 3.12
• SQLAlchemy
• Alembic
• PostgreSQL
• Pydantic
• Uvicorn
• Ruff
• Pytest
• Vue 3
• Nuxt
• Vuetify
• Vue Router
• MapLibre GL
• TypeScript
• Vitest
• pnpm
• Turborepo
• Docker Compose
• Playwright

Enfoque de ingenieria

Aunque es una demo MVP, el proyecto esta construido con una estructura pensada para crecer.

El backend sigue una arquitectura por capas:

• Routes: superficie HTTP y traduccion a respuestas de API.
• Services: reglas de aplicacion, orquestacion y transacciones.
• Repositories: acceso a datos y consultas.
• Models: definicion del esquema con SQLAlchemy.
• Schemas: contratos de entrada y salida con Pydantic.

Esta separacion ayuda a mantener responsabilidades claras. Por ejemplo, los repositorios no controlan transacciones; los servicios coordinan commit, rollback y operaciones de negocio.

En frontend, el proyecto tambien evita dispersar la logica critica: el admin centraliza su comunicacion con el backend en admin-api.ts, el storefront concentra la orquestacion de datos en useStorefrontPage.ts y los contratos compartidos viven en packages/types.

Valor del MVP

Este proyecto no busca ser solo una coleccion de pantallas. Su valor esta en demostrar como se puede disenar una experiencia de producto completa alrededor de datos geograficos.

El MVP muestra pensamiento de producto, capacidad full-stack, diseno de arquitectura, experiencia publica e interna, y una base escalable para evolucionar hacia funcionalidades mas complejas como busqueda por ciudad, filtros por servicios, carga masiva via CSV, geocodificacion automatica, roles administrativos, historial de cambios, publicacion programada, metricas o integraciones con proveedores de mapas.