SpecFlux Backend

API server for SpecFlux - AI-Powered Multi-Repo Development Orchestrator.

API Overview

REST API for managing AI-assisted software development workflows:

Resource	Description
Projects	Top-level containers grouping epics and tasks
PRDs	Product requirements documents with supporting files
Epics	Large features with acceptance criteria and task breakdown
Tasks	Individual work units with status, dependencies, and criteria
Repositories	Git repositories linked to projects
Skills	Claude Code skill definitions
Agents	Claude Code agent configurations

All endpoints require Firebase JWT authentication.

API-First Development

This project follows API-first design. All endpoints are defined in the OpenAPI spec before implementation:

1. Define endpoints in src/main/resources/openapi/api.yaml
2. Run mvn compile to generate controller interfaces
3. Implement the generated interfaces in controllers

When running locally, view the interactive spec at http://localhost:8090/swagger-ui.html

Prerequisites

• Java 25 (Temurin recommended)
• Maven 3.9+
• Docker (for PostgreSQL and Firebase emulator)

Java Installation (asdf)

asdf install java temurin-25.0.1+8.0.LTS
asdf set java temurin-25.0.1+8.0.LTS

Quick Start

mvn spring-boot:run

Docker Compose automatically starts PostgreSQL and Firebase Auth emulator.

The API will be available at http://localhost:8090

Tech Stack

• Spring Boot 4.0.0
• Java 25
• PostgreSQL
• Firebase Authentication
• Maven

Project Structure

This project follows Domain-Driven Design (DDD) with package-by-feature organization:

src/main/java/com/specflux/
├── SpecFluxApplication.java      # Main entry point
├── shared/                       # Shared kernel (base classes)
│   ├── domain/                   # Base domain classes
│   └── infrastructure/           # Cross-cutting concerns
├── user/                         # User bounded context
├── project/                      # Project bounded context
├── epic/                         # Epic bounded context
└── task/                         # Task bounded context

Each bounded context contains:
├── domain/                       # Core business logic
│   ├── model/                    # Entities, Value Objects, Aggregates
│   ├── repository/               # Repository interfaces
│   └── service/                  # Domain services
├── application/                  # Use cases
│   ├── dto/                      # Request/Response DTOs
│   ├── mapper/                   # Entity <-> DTO mappers
│   └── service/                  # Application services
├── infrastructure/               # Technical implementations
│   ├── persistence/              # JPA repositories
│   └── external/                 # External service adapters
└── interfaces/                   # Entry points
    └── rest/                     # REST controllers

Development

Build

# Compile
mvn clean compile

# Run tests (uses Testcontainers)
mvn test

# Package
mvn package

Run

# Development mode (default profile: dev)
mvn spring-boot:run

# With specific profile
mvn spring-boot:run -Dspring-boot.run.profiles=dev

Code Formatting

This project uses Spotless with Google Java Format.

# Check formatting
mvn spotless:check

# Apply formatting
mvn spotless:apply

Configuration

Profiles

Profile	Description	Usage
dev	Local development	Default profile, debug logging
test	Testing	Used by test classes, Testcontainers
prod	Production	Minimal logging, Swagger disabled

Environment Variables

Variable	Description	Default
SERVER_PORT	Server port	8090
SPRING_PROFILES_ACTIVE	Active profile	dev
DATABASE_URL	PostgreSQL URL	-
DATABASE_USERNAME	Database username	-
DATABASE_PASSWORD	Database password	-
FIREBASE_PROJECT_ID	Firebase project ID	-
GOOGLE_APPLICATION_CREDENTIALS	Path to Firebase service account JSON	-

Troubleshooting

Port already in use

# Find process using port 8090
lsof -i :8090

# Kill it
kill -9 <PID>

Database connection issues

1. Ensure PostgreSQL is running: docker ps | grep postgres
2. Check connection: psql -h localhost -U specflux -d specflux
3. Verify application-dev.yml has correct credentials

Firebase emulator not connecting

1. Ensure emulator is running: firebase emulators:start --only auth
2. Check emulator UI at http://localhost:4000
3. Verify FIREBASE_AUTH_EMULATOR_HOST=localhost:9099 is set

Tests failing with Testcontainers

1. Ensure Docker is running
2. Check Docker has sufficient resources
3. Try docker system prune to clean up old containers

Documentation

• CONTRIBUTING.md — How to contribute
• CODE_OF_CONDUCT.md — Community guidelines
• SECURITY.md — Report vulnerabilities

License

Elastic License 2.0 — Free for personal use. Commercial use restricted.