Follow Stelut on X (Twitter) Go to Stelut's GitHub repo Connect on LinkedIn Suscribirse al RSS

Springram

Springram: Social Demo with Spring Boot

Demonstration by Stelut Grigore Tomoiaga.

Springram is a small social network focused on showcasing production-style backend architecture with Spring Boot: REST API, JWT security, PostgreSQL persistence, and a Redis + Kafka layer to absorb social traffic without changing the API contract.

Demo: https://springram.steluttomoiaga.com Repo: https://github.com/StemiTomy/springram

What it solves

The project simulates a common social product scenario where likes, views, and comments can spike and overload the primary database. The goal is not just exposing endpoints, but designing a flow that stays fast and operationally reliable.

Technical architecture

  • Main backend in Spring Boot with a stateless design for horizontal scaling.
  • Remote PostgreSQL (managed) as the final source of truth.
  • Redis for low-latency counters and quick reads.
  • Kafka for decoupled social event ingestion.
  • Separate Preact frontend to validate the full end-to-end workflow.

The database remains external to keep responsibilities clean between durable storage and runtime services.

API (v1)

The API is organized by domain:

  • Auth: register, login, refresh, current user profile, language preferences.
  • Posts: create, paginated feed, idempotent likes, views, comments.
  • Search: suggestions and paginated results for posts or users.
  • Public analytics: aggregated summary with top words, top posts, hourly heatmap, and recent evolution.

Interactive endpoint docs: http://localhost:8080/swagger-ui/index.html.

Security and traceability

  • JWT authentication for private endpoints.
  • Bearer-token protection on profile and preference routes.
  • Middleware audit for GET /api/v1/auth/me with method, path, status, ip, user, and durationMs.
  • This log gives visibility into anonymous/authenticated access patterns and real response time.

Redis + Kafka to reduce DB pressure

Social interaction flow:

  1. API receives an action (like, view, comment).
  2. Counter is updated in Redis for fast response.
  3. Event is published to Kafka.
  4. Consumer persists to PostgreSQL with an idempotent pattern (INSERT ... ON CONFLICT).

Fallback behavior:

  • If Kafka is unavailable, the app writes directly to PostgreSQL.
  • If Redis is unavailable, counters are served/recomputed from PostgreSQL.

With async enabled, persistence is eventually consistent, while user-facing latency remains low.

Metrics and operational health

The project uses native Spring observability:

  • Actuator for health, readiness, and operational diagnostics.
  • Micrometer for technical and business metrics.
  • Social-specific metrics for Redis cache behavior, Kafka publish/consume, and database fallback.

In production, Actuator endpoints should be protected and not publicly exposed.

Migrations and data model

The schema strategy is based on Flyway:

  • Versioned SQL migrations in src/main/resources/db/migration.
  • Pending migrations applied automatically at startup.
  • Recommended flow: model entities, generate supporting DDL, curate SQL, and commit a clean Vx__...sql migration.

Design decision:

  • Flyway for simplicity and explicit SQL control.
  • Liquibase is considered when conditional deployments and advanced preconditions become necessary.

Testing strategy

Layered testing keeps feedback fast:

  • @WebMvcTest for controllers, security, and HTTP contract checks.
  • @DataJpaTest for repositories and persistence rules.
  • @SpringBootTest + MockMvc for full integration where required.

Current coverage includes key authentication behavior (401 without token), input validation, and unique-constraint persistence checks.

Scaling without Kubernetes

Deployment favors pragmatic simplicity:

  • Stateless app replicated horizontally with Docker Compose.
  • Auto-restart behavior for resilience on a single host.
  • External stateful database kept as a managed service.

As traffic grows, the natural next step is moving balancing/autoscaling to a dedicated orchestrator while preserving the same API contract.

Frontend (Preact)

The Springram by Stelut Tomoiaga frontend covers the core product flow:

  • Project landing page.
  • Auth (register/login).
  • Application view with profile, feed, and social actions.
  • Environment-based API target configuration for local/staging/production.

Main stack

  • Spring Web
  • Spring Security
  • Spring Data JPA
  • Spring Data Redis
  • Spring Kafka
  • PostgreSQL Driver
  • Flyway
  • Micrometer
  • Spring Boot Actuator
  • Lombok
  • Docker Compose Support

Technical references