README.md

Loopin API - Documentation Hub

Loopin is a high-performance backend API built with Java 21 and Spring Boot, designed for discovering interest-based local events, joining event groups, and coordinating with like-minded people through real-time group chat communication.

This directory contains the developer documentation for the Loopin API.

---

Table of Contents

• System Design & Flowcharts

  • System Architecture - Modules, vertical slices, CQRS conventions, rate limiting, and component diagrams.
  • Authentication Flow - Sequence diagrams detailing JWT authentication & Google OAuth.
  • Real-Time Chat - WebSocket gateway protocol, message persistence, and broadcast sequence.
  • Product Logic & User Flows - Logical flowcharts illustrating event discovery, group join approval, and coordination.

• Configuration & Reference

  • Database Design & Schema - Entity Relationship (ER) diagram, table descriptions, indices, and constraints.
  • PostgreSQL Performance Validation - Discovery indexes, cache invalidation, query plans, and k6 staging runs.
  • Environment Configuration - Environment variables checklist for local, staging, and production environments.
  • API Endpoint Reference - Comprehensive API specifications, request payloads, and response structures.
  • API Testing With Bruno - Git-friendly Bruno collection setup for local and staging backend validation.
  • Security Model - Security configuration, stateless authentication, role authorization, and moderation filter.

• Lifecycle & Operations

  • Deployment Guide - CI/CD pipeline and Cloud Run instructions.
  • Docker and Local Runtime - Dockerfile, Compose, local commands, and runtime environment variables.
  • Troubleshooting Reference - Common run-time errors, Liquibase lock management, and connection issues.
  • Project Roadmap - Short-term and long-term features roadmap.

• Architectural Decisions (ADR)

  • ADR 0001: Use Java 21
  • ADR 0002: Use Spring Boot 4.x
  • ADR 0003: Use PostgreSQL + Liquibase
  • ADR 0004: Use JWT Stateless Auth
  • ADR 0005: Use Layered Service Architecture
  • ADR 0006: Use Public UUID Identifiers
  • ADR 0007: Use Bucket4j Rate Limiting
  • ADR 0008: Use REST Plus STOMP WebSocket Chat
  • ADR 0009: Use Environment-Driven Container Deployment
  • ADR 0010: Use Async AI Recommendation Boundary
  • ADR 0011: Incremental Events Vertical Slices
  • ADR 0012: Lightweight CQRS And Module APIs

---

Core Technology Stack

• Runtime: Java 21 (LTS)
• Framework: Spring Boot 4.1.0 (with Web, Data JPA, Security, and Redis)
• Database: PostgreSQL
• Schema Management: Liquibase Migrations
• Rate Limiting: Bucket4j + Lettuce (Redis)
• Security: JSON Web Tokens (JWT) + Google OAuth integration
• Containerization: Docker & Docker Compose
• Performance & Query Optimization: Batch-fetching (left join fetch) for event-interest associations to prevent N+1 query patterns; Spring Cache with Redis provider.

---

Quick Start Guide

1. Prerequisite Setup

Ensure you have the following installed on your machine:

• Java Development Kit (JDK) 21
• Maven 3.9+
• Docker & Docker Compose
• PostgreSQL client

2. Configure Environment

Clone the repository and copy the environment template to create your .env file:

cp .env.example .env

Open .env and fill in the required variables (database credentials, JWT secrets, etc.). Refer to Environment Configuration for more details.

3. Spin up Infrastructure

Launch PostgreSQL, Redis, and the API using Docker Compose:

docker compose up --build -d

4. Run Schema Migrations

Liquibase runs pending migrations automatically on application startup. To run migrations manually:

mvn liquibase:update

5. Start the Application

Run the Spring Boot application using the local profile:

mvn spring-boot:run -Dspring-boot.run.profiles=local

The application will start, by default listening on http://localhost:8080/api/v1. The interactive Swagger UI is available at http://localhost:8080/api/swagger-ui.html.

---

API Testing

API endpoints can be tested using the Bruno API client. The collection is located in /api-tests/bruno, with local and staging example environments. See API Testing With Bruno for setup, authentication workflow, and safe Git hygiene.

1. Download and install Bruno.
2. Import the collection folder into Bruno.
3. Select the Local environment configuration.
4. Add local-only values for auth_token, google_id_token, and resource IDs.
5. Execute requests.