HomeFix Backend

A production-minded marketplace backend for connecting people who need home repairs with trusted local professionals.

HomeFix is a real, runnable MVP built as a one-week vibecoding experiment. The goal was simple: combine modern backend technologies with AI-assisted development and see how far a small team of one human and several AI tools could go in a short, focused delivery window.

Why this project exists

HomeFix was created for a vibecoding test: build a useful MVP in one week while deliberately exploring the newest practical technologies and AI-assisted workflows.

The project was developed collaboratively with:

• Claude — shaped the initial product idea and decomposed the work into tasks in Notion.
• Codex — implemented most of the backend code and helped iterate quickly.
• Lovable — generated the product/UI direction and frontend design language.
• ChatGPT — supported small implementation questions, decisions, and debugging moments.
• Human direction — defined the architecture, made product decisions, reviewed the output, and edited code where needed.

The result is intentionally more than a prototype: it includes real authentication, persistence, migrations, payments, object storage, realtime messaging, validation, tests, health checks, and a containerized runtime.

Product flow

Customer creates a task
        ↓
Professionals discover the task and submit offers
        ↓
Customer accepts an offer
        ↓
The participants chat in realtime
        ↓
Payment is created and confirmed through Stripe
        ↓
The customer leaves a review

Features

• Customer and professional accounts with role management.
• Email/password authentication with JWT access and refresh tokens.
• Google sign-in token verification.
• Browse service categories and create, list, view, and update tasks.
• Professional profiles and profile updates.
• Offer submission and offer acceptance workflow.
• Conversations and message history linked to tasks.
• Realtime task chat over WebSocket/STOMP with JWT handshake protection.
• Image uploads to an S3-compatible object store (Cloudflare R2).
• Stripe payment intent creation, confirmation, and webhook handling.
• Reviews for completed work and professional review listings.
• Bean validation and consistent global error responses.
• PostgreSQL persistence with versioned Flyway migrations.
• OpenAPI/Swagger documentation.
• Actuator health endpoint for container and deployment monitoring.
• Unit, integration, architecture, marketplace-flow, and WebSocket tests.

Architecture

The backend follows a pragmatic clean/hexagonal architecture. Dependencies point inward toward the domain, while external concerns are isolated behind ports and adapters.

presentation       HTTP/WebSocket controllers and API error handling
        ↓
application        use cases, services, DTOs, inbound/outbound ports
        ↓
domain             entities, value-oriented models, and business statuses
        ↑
infrastructure     Spring Data, PostgreSQL, JWT, Google, Stripe, R2, WebSocket

This structure keeps business workflows independent of Spring and vendor-specific integrations. For example, payments, image storage, token verification, and repositories are represented as application ports and implemented in infrastructure adapters.

Database schema changes live in src/main/resources/db/migration and are applied automatically by Flyway. Hibernate validates the mapped schema at runtime rather than silently creating it.

Technologies & services

Area	Choice
Language	Kotlin 2.3.21
Runtime	Java 21
Framework	Spring Boot 4.1.0
API	Spring MVC, Bean Validation, OpenAPI 3 / Swagger UI
Realtime	Spring WebSocket with STOMP
Persistence	Spring Data JPA, Hibernate, PostgreSQL
Migrations	Flyway
Security	Spring Security, JWT, BCrypt, Google authentication
Payments	Stripe
File storage	Cloudflare R2 via AWS S3 SDK
Operations	Spring Boot Actuator, Docker, Docker Compose
Testing	JUnit 5, Spring Boot Test, Spring Security Test, H2 for test runtime
Build	Gradle Kotlin DSL

Screenshots

https://fixhub-app-design.lovable.app

Deployment

The backend is deployed on Render using the project’s Docker configuration. Production environment variables follow the same names documented in .env-example, including database, JWT, Stripe, Google, and Cloudflare R2 settings.

Run locally with Docker

Prerequisites

• Docker Desktop with Docker Compose.
• A PostgreSQL database reachable from the API container. The current Compose file builds and runs the API; database provisioning is intentionally external, so provide the database URL in .env.

Setup

1. Copy the example environment file:

   cp .env-example .env

   On PowerShell:

   Copy-Item .env-example .env

2. Fill in at least DB_URL, DB_USERNAME, DB_PASSWORD, and JWT_SECRET. Add Google, Stripe, and R2 values when using those integrations. Keep .env private.

3. Build and start the API:

   docker compose up --build

The API is available at http://localhost:8080 by default. Change the host port with APP_PORT, for example APP_PORT=9090.

Useful endpoints:

• Swagger UI: http://localhost:8080/swagger-ui
• OpenAPI JSON: http://localhost:8080/v3/api-docs
• Health: http://localhost:8080/actuator/health

Stop the service with:

docker compose down

Run without Docker

With Java 21 and a configured PostgreSQL instance available:

./gradlew bootRun

On Windows:

.\gradlew.bat bootRun

Run the test suite with ./gradlew test or .\gradlew.bat test on Windows.

Configuration

All runtime configuration is environment-based. The complete variable list is documented in .env-example. Important integrations are optional at the application level, but database connectivity and JWT_SECRET are required for a useful local run.

Contributing

Contributions, fixes, and thoughtful feedback are welcome.

1. Fork the repository and create a focused branch.
2. Make the smallest coherent change possible.
3. Add or update tests for behavior you change.
4. Run the test suite before opening a pull request.
5. Describe the problem, the solution, and any configuration changes.

Please never commit .env, credentials, payment secrets, or cloud access keys. For larger product or architecture changes, open an issue first so the direction can be discussed.

Roadmap

The MVP is intentionally compact. Natural next steps include production-grade refresh-token rotation and revocation, richer search and geo-filtering, notifications, automated CI/CD, observability beyond health checks, stronger rate limiting, and a full local Compose profile with PostgreSQL included.

License

This project is intended to be released under the MIT License. Add a LICENSE file with the standard MIT text before publishing or redistributing the repository.

AI-assisted development tooling

The project was developed with Codex, Claude, ChatGPT, and Lovable. Headroom was used with Codex to reduce unnecessary token usage and make the AI-assisted coding workflow more efficient.

A note on AI-assisted development

“Vibecoding” made the iteration loop dramatically faster, but it did not remove engineering responsibility. Architecture, security boundaries, data ownership, integration contracts, test coverage, and final review still required human judgment. That is part of the experiment—and one of the most interesting outcomes of HomeFix.

---

Built in one week with curiosity, constraints, and a little help from several very patient AI collaborators.