Internal operations management system for multi-unit restaurant chains.

FlowChain replaces manual WhatsApp and Excel-based workflows with a structured, traceable, and role-based REST API — covering weekly supply orders, warehouse stock control, distribution planning, daily chicken stock tracking, urgent inter-unit transfers, and supplier payment registration.

The system follows a Layered Architecture with clear separation of concerns:

Client (Mobile App / Browser)
        ↓ HTTP Request + JWT
Spring Security Filter
        ↓ Authorized
Controller Layer     ← Receives HTTP requests, validates DTOs
        ↓
Service Layer        ← Business logic, validations, aggregations
        ↓
Repository Layer     ← Spring Data JPA, database communication
        ↓
PostgreSQL Database

The system manages 7 operational units:

• Requirements analysis
• Data model design (12 entities)
• System architecture diagram
• Spring Boot 3.x project setup
• GitHub repository initialization
• Docker Compose — PostgreSQL + pgAdmin
• Project folder structure
• Unit entity with JPA mappings
• UnitRepository, UnitService, UnitController
• First REST endpoint — GET /api/units
• Swagger UI integration

• User registration & login
• JWT token generation and validation
• Role-based access control (ADMIN, WAREHOUSE, UNIT, COURIER)
• Security filter configuration

• Weekly order submission per unit (Supplier, Warehouse, Beira Sumos)
• Prepared dishes order (soup, rice, bacalhau, etc.)
• Automatic consolidated order list per supplier
• Order status tracking (PENDING → CONFIRMED → DELIVERED)

• Warehouse stock entries and exits
• Weekly distribution planning per unit
• Portioning registration (Alpha & Beta units)
• Delivery confirmation per unit

• Daily chicken stock control (per unit)
• Urgent product transfers between units
• Supplier payment registration with invoice photo
• Operations history and audit trail

• Unit tests with JUnit 5 + Mockito
• Integration tests
• Full Swagger / OpenAPI documentation
• API usage examples

• Global exception handling
• Input validation on all endpoints
• System logging
• Security review

flowchain-api/
├── docs/                          # Project documentation (PDF)
│   ├── FlowChain_Analise_Requisitos.pdf
│   ├── FlowChain_Modelo_Dados.pdf
│   ├── FlowChain_Arquitetura.pdf
│   └── FlowChain_UseCases.html
├── src/
│   ├── main/
│   │   ├── java/com/flowchain/api/
│   │   │   ├── controller/        # REST Controllers
│   │   │   ├── service/           # Business logic
│   │   │   ├── repository/        # Spring Data JPA repositories
│   │   │   ├── entity/            # JPA entities (database tables)
│   │   │   ├── dto/               # Data Transfer Objects
│   │   │   ├── security/          # JWT & Spring Security config
│   │   │   └── exception/         # Global exception handling
│   │   └── resources/
│   │       └── application.yml    # App configuration
│   └── test/                      # Unit & integration tests
├── docker-compose.yml             # PostgreSQL + pgAdmin containers
├── pom.xml                        # Maven dependencies
└── README.md

• Java 21
• Docker + Docker Compose
• Maven 3.x

1. Clone the repository

git clone https://github.com/CLopes86/flowchain-api.git
cd flowchain-api

2. Start the database

docker compose up -d

3. Run the application

./mvnw spring-boot:run

4. Access Swagger UI

http://localhost:8080/swagger-ui/index.html

Full project documentation is available in the /docs folder:

• 📋 Requirements Analysis
• 🗄️ Data Model
• 🏗️ Architecture Diagram
• 📊 Use Case Diagram

Cesaltino Lopes Computer Science Student @ IPCB — Castelo Branco, Portugal

This project is under active development. New features are added progressively following the roadmap above.