FlowChain API

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.

---

🚀 Tech Stack

Technology	Version	Purpose
Java	21 (LTS)	Programming language
Spring Boot	3.5.13	Main framework
Spring Security + JWT	Latest	Authentication & authorization
Spring Data JPA + Hibernate	3.x	Database ORM
PostgreSQL	16	Relational database
Docker + Docker Compose	Latest	Containerization
Maven	3.x	Build & dependency management
JUnit 5 + Mockito	Latest	Unit & integration testing
Swagger / OpenAPI	2.8.8	API documentation
Lombok	Latest	Boilerplate reduction

---

🏗️ Architecture

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

---

👥 System Roles

Role	Description
ADMIN	Full access — consolidated lists, all units, user management
WAREHOUSE	Stock management, distributions, delivery confirmation
UNIT	Weekly orders, daily chicken stock, payment registration
COURIER	Urgent transfers between units

---

🏪 Operational Units

The system manages 7 operational units:

Unit	Type	Special Role
Alpha	Restaurant	Portioning center — bacalhau & entrecosto
Beta	Restaurant + Take Away	Operations hub — soups, rice, prepared dishes + courier base
Gamma	Restaurant + Take Away	—
Delta	Restaurant + Take Away	—
Epsilon	Take Away	—
Zeta	Take Away	—
Eta	Take Away	—

---

📅 Weekly Operational Calendar

Day	Operation	Responsible
Monday	Charcoal distribution	Warehouse
Tuesday	Warehouse products distribution	Warehouse
Thursday	External supplier purchases + distribution	Admin + Warehouse
Friday	Meats & prepared dishes distribution	Warehouse
Daily	Chicken stock control	Each Unit
Any time	Urgent transfers between units	Courier

---

🗺️ Project Roadmap

✅ Phase 1 — Setup & Foundations (Completed)

• 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

🔄 Phase 2 — Authentication (In Progress)

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

⏳ Phase 3 — Order Management

• 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)

⏳ Phase 4 — Warehouse & Stock Management

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

⏳ Phase 5 — Daily Operations

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

⏳ Phase 6 — Testing & Documentation

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

⏳ Phase 7 — Security & Quality

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

---

📁 Project Structure

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

---

🐳 Running Locally

Prerequisites

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

Steps

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

---

📋 Main API Endpoints (Work in Progress)

Method	Endpoint	Role	Description
GET	/api/units	All	List all units
GET	/api/units/{id}	All	Get unit by ID
POST	/api/units	ADMIN	Create new unit
DELETE	/api/units/{id}	ADMIN	Delete unit
POST	/api/auth/login	All	User login
POST	/api/orders	UNIT	Submit weekly order
GET	/api/orders/consolidated	ADMIN, WAREHOUSE	Consolidated order list
POST	/api/warehouse/stock	WAREHOUSE	Register stock movement
POST	/api/distributions	WAREHOUSE	Create distribution
PUT	/api/distributions/{id}/confirm	WAREHOUSE	Confirm delivery
POST	/api/chicken-stock	UNIT	Daily chicken stock
POST	/api/transfers	COURIER	Register urgent transfer
POST	/api/payments	UNIT	Register supplier payment

---

📄 Documentation

Full project documentation is available in the /docs folder:

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

---

👨‍💻 Author

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

---

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