OpenSpace Manager - Project Context for AI

Project Overview

OpenSpace Manager is a backend application built with Java and Spring Boot. Its primary purpose is to manage flexible office spaces, specifically focused on handling:

• Companies
• Offices
• Floors (within offices)
• Desks
• Bookings (employees booking desks)
• Users (Employees and Admins)

The system is designed to serve as a REST API for a frontend application (e.g., React/Vue) or mobile app that allows employees to reserve work spots and administrators to manage the layout and resources.

Technology Stack

• Language: Java 17 (as per pom.xml)
• Framework: Spring Boot 4.0.1 (Experimental/Custom)
• Build Tool: Maven
• Database: PostgreSQL (Runtime), H2 (Test)
• Persistence: Spring Data JPA (Hibernate)
• Security: Spring Security with JWT (JSON Web Tokens) for authentication and authorization.
• Real-time: WebSockets (STOMP)
• Validation: Java Bean Validation (Hibernate Validator)
• Documentation: Swagger/OpenAPI (SpringDoc 2.8.3)
• Containerization: Docker (see docker-compose.yml)
• Utilities: Lombok

Core Domain Models

1. Company: The top-level entity. An organization that uses the system.
2. Office: A physical building or location belonging to a Company.
3. Floor: A specific level within an Office.
4. Desk: A bookable unit located on a Floor. It has attributes like:
   • number/identifier
   • status (Available, Occupied, etc.)
   • equipment (Monitor, dual screen, etc.)
5. User: Accounts for employees and admins.
   • Roles: ADMIN, USER.
6. Booking: A reservation of a specific Desk by a User for a specific Date/Time range.

Key Features & Workflows

• Authentication: Users register and login to receive a JWT.
• Space Management (Admin):
  • CRUD operations for Companies, Offices, Floors, and Desks.
  • Define desk capacity and layout.
• Booking System (User):
  • Search for available desks by date and location.
  • Create, View, and Cancel bookings.
  • Validation rules (e.g., cannot book an occupied desk, user cannot have overlapping bookings).
  • Real-time updates via WebSockets.
• Data Seeding: Contains a DataSeeder to populate the database with initial demo data (admin user, sample offices, etc.) on startup.
• Error Handling: Global exception handling (GlobalExceptionHandler) to return standardized JSON error responses.

Project Structure

• src/main/java/com/openspace/manager:
  • config/: Security config, CORS, Seeders, Global Exception handlers.
  • controller/: REST endpoints (API layer).
  • service/: Business logic.
  • repository/: Database interactions (Interfaces extending JpaRepository).
  • model/ or entity/: JPA Entities mapping to DB tables.
  • dto/: Data Transfer Objects for API requests/responses (e.g., DeskRequest, LoginRequest).
  • security/: JWT filters, UserDetails implementation.

Getting Started (Local Development)

Como el proyecto utiliza una arquitectura de microservicios, la forma más sencilla de arrancar el backend en local (con tus propias bases de datos aisladas) es usar Docker Compose.

1. Requisitos Previos

• Tener Docker Desktop o Docker Engine instalado y ejecutándose.
• Tener Java 17 y Maven instalados (opcional si usas el wrapper mvnw).

2. Arrancar la Infraestructura

En la raíz del proyecto, ejecuta el siguiente comando para levantar la base de datos PostgreSQL, Redis, RabbitMQ, Zipkin, Prometheus y Grafana de golpe:

docker-compose up -d

(Nota: El archivo application.yml está configurado por defecto para apuntar a localhost y a los puertos estándar expuestos por estos contenedores).

3. Ejecutar la Aplicación Spring Boot

Con la infraestructura viva, arranca tu servidor Java:

./mvnw spring-boot:run

---

Deployment de Producción (Cloud - Free Tier)

Este proyecto está preparado para desplegarse en la nube 100% gratis utilizando una combinación de servicios Serverless y PaaS.

La arquitectura en producción inyecta variables de entorno para reemplazar el localhost y apuntar a estos servicios en la nube:

1. Enlaces a los Dashboards (Entorno de Producción)

Si necesitas revisar el estado de la base de datos, ver los datos de Redis o reiniciar el backend, utiliza los siguientes enlaces:

• 🐘 Base de Datos Principal (PostgreSQL Serverless): Alojada en Neon.tech
• ⚡ Caché / Lock System (Redis Serverless): Alojado en Upstash
• 🐇 Message Broker (RabbitMQ): Alojado en CloudAMQP
• ☁️ Servidor del Backend (Spring Boot Web Service): Alojado y desplegado en Render.com (Incluye los Logs en vivo del servidor)

2. Cómo replicar el despliegue desde cero

Si por alguna razón se pierden los servicios actuales, estos son los pasos para levantarlo de nuevo en los mismos proveedores:

1. Código fuente: Asegúrate de que el repositorio en GitHub tenga el Dockerfile en el directorio raíz.
2. Preparar los servicios satélite: Crea bases de datos gratuitas en Neon, Upstash y CloudAMQP. Extrae los credenciales de los paneles de control.
3. Desplegar el Backend: Abre una cuenta en Render, crea un "Web Service", vincúlalo a este repositorio Git y elige el plan "Free" (0$/mes).
4. Inyectar Secretos (.env): En la pestaña Environment de Render, inyecta las variables contenidas en el archivo .env del proyecto con tus credenciales actualizadas (sustituyendo las actuales):
   • SPRING_DATASOURCE_URL, SPRING_DATASOURCE_USERNAME, SPRING_DATASOURCE_PASSWORD
   • SPRING_REDIS_HOST, SPRING_REDIS_PORT, SPRING_REDIS_PASSWORD, SPRING_REDIS_SSL=true
   • SPRING_RABBITMQ_HOST, SPRING_RABBITMQ_PORT, SPRING_RABBITMQ_VIRTUAL_HOST, SPRING_RABBITMQ_USERNAME, SPRING_RABBITMQ_PASSWORD, SPRING_RABBITMQ_SSL_ENABLED=true
   • MANAGEMENT_TRACING_ENABLED=false (Para evitar el colapso de RAM en el plan gratuito).

---

API Usage Flow (Quick Start)

1. Login as Admin (admin@openspace.com / admin123) to get a Token.
2. Create Structure: Create Company, Office, and Floor via /api/structure/....
3. Create Desk: POST to /api/desks linked to a Floor.
4. Book: POST to /api/bookings (Creates a LOCK).
5. Confirm: POST to /api/bookings/{id}/confirm within 5 minutes.

WebSocket

Connect to /ws. Subscribe to /topic/bookings for live updates on locks and unlocks.