UniVaal is a production e-commerce platform serving university students in the Vaal region of South Africa.
This repository contains the backend API for the UniVaal MVP, built to production standards and designed to scale cleanly over time.
- Exposes the public product catalog (including product images and category)
- Supports cart, checkout flow, and handles payment confirmation
- Creates orders and manages basic order status flow
- Provides API-level admin capabilities for product and image management
- Publishes a formal OpenAPI specification as the source of truth for integration
Out of scope for the current MVP:
- Inventory management and fulfillment domain
- Delivery tracking domain
- Admin exists only for product and image management during MVP.
- Design approach: Layered domain separation, Domain-Driven inspired architecture.
- API strategy: API-first development
- Specification: OpenAPI is treated as the contract and integration reference
- Goal: predictable behavior, clean boundaries, and maintainable evolution
Controller → Application → Domain → Adapter → DB
- Language: Java
- Database: PostgreSQL
- API Style: REST (OpenAPI-driven)
domain/— core business models and rulesinfrastructure/— persistence, integrations, external systemsv1/admin/application— use-cases and orchestrationv1/admin/interfaces— delivery layer
Note: folder naming may vary, but the intent remains the same: domains stay clean and independent, avoid mixing concerns.
The OpenAPI specification in this repo is the integration contract for UniVaal.
All updates go through the OpenAPI spec.
The API uses semantic versioning. Breaking changes are introduced in new major versions (like v2).
Frontend should align to the spec and treat changes as versioned, reviewed contract updates.
This backend is an actively developed production MVP.
Changes are expected, but the system is being built with long-term stability and maintainability in mind.