Trix Backend

Spring Boot backend for the Trix social platform. This service covers authentication, users, posts, comments, follows, notifications, search indexing, media upload/storage, Trix short videos, settings, SMTP email flows, OAuth2 login, Valkey caching, Kafka/WebSocket realtime events, and async media processing.

Quick Start

Prerequisites

• Java 21
• Maven
• MySQL or H2 for local development
• Valkey if you want cache-backed rate limiting and cached reads
• Kafka if you want realtime notifications and async media jobs
• SMTP credentials if you want password reset and verification emails to send for real

Run Locally

mvn spring-boot:run

By default the app starts on http://localhost:8080 and uses H2 for local development.

Main URLs

• API base: http://localhost:8080/api/v1
• Swagger UI: http://localhost:8080/swagger-ui.html
• OpenAPI JSON: http://localhost:8080/v3/api-docs
• Health: http://localhost:8080/api/v1/health
• Actuator health: http://localhost:8080/actuator/health
• Actuator info: http://localhost:8080/actuator/info

Configuration

Use environment variables to switch between local and production services.

Variable	Purpose	Default
TRIX_DB_URL	Database JDBC URL	H2 in-memory
TRIX_DB_USERNAME	Database username	sa
TRIX_DB_PASSWORD	Database password	empty
TRIX_JWT_SECRET	JWT signing secret	change-this-secret-before-production-use
TRIX_FRONTEND_BASE_URL	Frontend redirect base	http://localhost:5173
TRIX_OAUTH2_REDIRECT_URI	OAuth2 success redirect	http://localhost:5173/auth/oauth2/success
TRIX_SMTP_HOST	SMTP host	localhost
TRIX_SMTP_PORT	SMTP port	1025
TRIX_SMTP_USERNAME	SMTP username	empty
TRIX_SMTP_PASSWORD	SMTP password	empty
TRIX_MAIL_FROM	Sender address	no-reply@trix.local
TRIX_GOOGLE_CLIENT_ID	Google OAuth client id	empty
TRIX_GOOGLE_CLIENT_SECRET	Google OAuth client secret	empty
TRIX_GITHUB_CLIENT_ID	GitHub OAuth client id	empty
TRIX_GITHUB_CLIENT_SECRET	GitHub OAuth client secret	empty
TRIX_VALKEY_HOST	Valkey host	localhost
TRIX_VALKEY_PORT	Valkey port	6379
TRIX_KAFKA_BOOTSTRAP_SERVERS	Kafka bootstrap servers	localhost:9092
TRIX_STORAGE_PROVIDER	local or object-storage	local
TRIX_MEDIA_STORAGE_DIR	Local media directory	temp folder
TRIX_OBJECT_STORAGE_ENDPOINT	S3-compatible endpoint	empty
TRIX_OBJECT_STORAGE_BUCKET	Object storage bucket	empty
TRIX_OBJECT_STORAGE_ACCESS_KEY_ID	Object storage access key	empty
TRIX_OBJECT_STORAGE_SECRET_ACCESS_KEY	Object storage secret key	empty
TRIX_OBJECT_STORAGE_PUBLIC_BASE_URL	Public media URL base	empty

Storage Modes

• local: files are written to the local media directory and served from /media/**
• object-storage: files are stored in an S3-compatible object store

API Overview

Auth

• POST /api/v1/auth/register
• POST /api/v1/auth/login
• POST /api/v1/auth/refresh
• POST /api/v1/auth/logout
• POST /api/v1/auth/password-reset/request
• POST /api/v1/auth/password-reset/confirm
• POST /api/v1/auth/email-verification/request
• POST /api/v1/auth/email-verification/confirm
• POST /api/v1/auth/mfa/setup
• POST /api/v1/auth/mfa/verify
• POST /api/v1/auth/mfa/disable
• GET /api/v1/auth/oauth2/providers
• POST /api/v1/auth/oauth2/link

Users and Follows

• GET /api/v1/users/me
• PUT /api/v1/users/me
• GET /api/v1/users/{username}
• GET /api/v1/users/search?q=...
• POST /api/v1/users/{userId}/follow
• DELETE /api/v1/users/{userId}/follow
• GET /api/v1/users/{userId}/followers
• GET /api/v1/users/{userId}/following

Posts and Comments

• POST /api/v1/posts
• GET /api/v1/posts/{postId}
• PUT /api/v1/posts/{postId}
• DELETE /api/v1/posts/{postId}
• GET /api/v1/posts/feed
• GET /api/v1/posts/user/{userId}
• POST /api/v1/posts/{postId}/like
• DELETE /api/v1/posts/{postId}/like
• POST /api/v1/posts/{postId}/repost
• POST /api/v1/posts/{postId}/bookmark
• GET /api/v1/posts/{postId}/comments
• POST /api/v1/posts/{postId}/comments

Media

• POST /api/v1/media/upload
• POST /api/v1/media/upload/external
• DELETE /api/v1/media/{mediaId}
• GET /api/v1/media/{mediaId}/thumbnail

Search, Settings, Notifications, Trix

• GET /api/v1/search?q=...
• GET /api/v1/settings
• PUT /api/v1/settings
• GET /api/v1/settings/sessions
• DELETE /api/v1/settings/sessions/{sessionId}
• GET /api/v1/notifications
• PUT /api/v1/notifications/{id}/read
• PUT /api/v1/notifications/read-all
• DELETE /api/v1/notifications/{id}
• POST /api/v1/trix
• GET /api/v1/trix/{trixId}
• GET /api/v1/trix/feed
• GET /api/v1/trix/featured
• POST /api/v1/trix/{trixId}/like
• POST /api/v1/trix/{trixId}/view

Response Shapes

The most important response types are:

• AuthResponse: access token, refresh token, expiry, and current user
• UserProfileResponse: user profile summary
• PostResponse: post details and counters
• CommentResponse: comment details and counters
• MediaResponse: uploaded media metadata and processing status
• SearchResponse: matched users and posts
• NotificationResponse: notification list items
• TrixResponse: short video details and counters

Swagger

Swagger UI is enabled at http://localhost:8080/swagger-ui.html. Use the Authorize button and paste your JWT access token as a bearer token:

Bearer <your-access-token>

The generated OpenAPI spec is available at http://localhost:8080/v3/api-docs.

Postman

Import the collection from:

• docs/postman/trix-backend.postman_collection.json
• docs/postman/trix-backend.postman_environment.json

After login, save the accessToken and refreshToken variables in the Postman environment.

Notes

• H2 is enabled for local development.
• Real email delivery requires SMTP configuration.
• OAuth2 login requires Google or GitHub client credentials.
• Kafka must be running for realtime notifications and async media jobs.
• Valkey is used for cache-backed rate limiting and cached hot reads.

Author

• Ritesh Gupta
• ritesh97935gupt@gmail.com
• https://linkedin.com/in/rit3sh-6upta/