🏢 SGVS API - Simplified Sales Management System

📋 Description

SGVS API is a robust RESTful backend application built with Spring Boot that provides complete management capabilities for sales, inventory, customers, and expenses. Designed to deliver a "CEO experience" with business intelligence, the API integrates real-time inflation tracking and delivers analytical reports to help small and medium-sized businesses optimize their financial operations.

API Response in Insomnia

Here's an example of an authenticated request successfully returning a product list:

GET http://localhost:8081/api/v1/products
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

✅ Status: 200 OK

{
  "data": [
    {
      "id": 1,
      "name": "Product A",
      "sku": "SKU-001",
      "cost": 50.00,
      "price": 99.90,
      "profitMargin": 99.80,
      "stock": 150,
      "category": "Electronics"
    },
    {
      "id": 2,
      "name": "Product B",
      "sku": "SKU-002",
      "cost": 30.00,
      "price": 79.90,
      "profitMargin": 166.33,
      "stock": 45
    }
  ],
  "meta": {
    "total": 2,
    "page": 0,
    "limit": 20
  }
}

💡 Tip: All responses follow consistent RESTful patterns with appropriate HTTP status codes (200 OK, 400 Bad Request, 401 Unauthorized, 500 Server Error).

🛠 Technologies Used

Backend

Java 21 — Modern language with cutting-edge features
Spring Boot 3.5.3 — Web framework and security
Spring Data JPA — Object-relational mapping (ORM)
Spring Security + JWT — Stateless authentication with tokens
OAuth2 Google — Integrated social login

Database

PostgreSQL — Robust relational database
Hibernate — ORM for automatic persistence

External Integration

Google OAuth 2.0 — Authentication via Google

Tools & Quality

Maven — Dependency management and build automation
Lombok — Reduces boilerplate (getters, setters, constructors)
JUnit 5 + Mockito — Unit testing with coverage
Docker — Containerization for deployment

✨ Key Features

🔐 Authentication & Security

✅ User registration and login with robust validation
✅ JWT authentication with configurable token expiration
✅ Google OAuth 2.0 login with integrated profile
✅ Role-based access control (ADMIN, USER)

📦 Product Management

✅ Complete CRUD operations on products
✅ Automatic profit margin calculation
✅ Inventory control (global, per-item, or disabled)
✅ Categorization and unique SKU
✅ ABC report (top-selling products)

👥 Customer Management

✅ Complete CRUD for customers with contact validation
✅ Advanced filters and pagination
✅ Purchase history tracking
✅ Support for generic customer (sale without specific customer)

💰 Sales Management

✅ Sales recording with multiple items
✅ Automatic calculation of totals (gross and net)
✅ Per-item discount control
✅ Automatic inventory updates
✅ Sales reports by period

💸 Expense Management

✅ Registration of operational expenses
✅ Restocking expenses (automatically update inventory)
✅ Expense categorization
✅ Advanced filters and reports

📊 Dashboard & Reports

✅ Summary metric cards (revenue, profit, inventory)
✅ Sales evolution charts
✅ Product ABC report
✅ Integration with Central Bank inflation indices

🌍 Global Settings

✅ Inventory control modes (global, per-item, or disabled)
✅ Currency and localization
✅ Business parameters (default margins, etc.)

🎓 The Process and Learnings

The Process

We started by designing the database schema based on a real-world sales management business model. The greatest challenge was balancing ease of use with business robustness — many startups fail because they over-engineer simple things.

The first major milestone was implementing the Products and Sales API with precise profit calculations. We faced initial challenges with:

Automatic inventory updates — We needed to synchronize sales and restocking expenses without creating inconsistencies. Solution: transactions with @Transactional in Spring.
Efficient pagination — Thousands of records loading slowly. Solution: database indices on PostgreSQL + optimized queries with @Query in JPA.
Inflation integration — We needed to fetch Central Bank indices but with safe fallback. Solution: scheduled task that updates cache periodically.

What I Learned

This project forced me to deeply understand:

Spring Security: Configuring JWT correctly is non-trivial. I now understand why many projects fail with token leaks.
Transaction Management: Operations modifying multiple tables require careful isolation. I learned when to use @Transactional and isolation levels.
API Design: Consistent naming, versioning (/api/v1/), and standardized responses make ALL the difference in maintainability.
Testing Strategy: Unit tests in services with Mockito revealed bugs that manual testing never caught, especially in calculation logic.
Infrastructure: Docker + PostgreSQL in production is different from h2 in tests. I learned about connectionPool, timeout, and real performance.

🚀 How to Run the Project

If you just want to USE the project, just click on the URL https://sgvs-ui.onrender.com/

TO DEVELOPERS

Prerequisites

You'll need to have installed:

Java 21+ (Download)
Maven 3.8+ (usually comes with IDEs like IntelliJ or Eclipse)
PostgreSQL 12+ (Download)
Git to clone the repository

Step 1: Clone the Repository

git clone https://github.com/your-username/sgvs-api.git
cd sgvs-api

Step 2: Configure Environment Variables

Copy the example file:

cp .env.example .env

Edit the .env file and set real values:

# Database
DB_PASSWORD=your-postgres-password-here

# JWT Secret (generate a random string with at least 32 characters)
# Tip: use `openssl rand -base64 32` to generate automatically
JWT_SECRET_KEY=your-random-32-character-minimum-secret-key-here

⚠️ IMPORTANT: Never commit real passwords! Use environment variables in production.

Step 3: Configure PostgreSQL Database

Create the database:

CREATE DATABASE sgvs_db;
CREATE USER postgres WITH PASSWORD 'your-postgres-password-here';
GRANT ALL PRIVILEGES ON DATABASE sgvs_db TO postgres;

Or use Docker (recommended):

docker run --name sgvs-postgres \
  -e POSTGRES_PASSWORD=your-password \
  -e POSTGRES_DB=sgvs_db \
  -p 5432:5432 \
  -d postgres:latest

Step 4: Export Environment Variables

On Linux/macOS:

export DB_PASSWORD='your-postgres-password-here'
export JWT_SECRET_KEY='your-random-32-character-minimum-secret-key-here'
export GOOGLE_CLIENT_ID='your-google-client-id'
export GOOGLE_CLIENT_SECRET='your-google-client-secret'

On Windows (PowerShell):

$env:DB_PASSWORD = 'your-postgres-password-here'
$env:JWT_SECRET_KEY = 'your-random-32-character-minimum-secret-key-here'
$env:GOOGLE_CLIENT_ID = 'your-google-client-id'
$env:GOOGLE_CLIENT_SECRET = 'your-google-client-secret'

Step 5: Run the Application

# With Maven wrapper (recommended)
./mvnw spring-boot:run

# Or with globally installed Maven
mvn spring-boot:run

The application will start at: http://localhost:8081

Step 6: Verify It's Running

curl http://localhost:8081/actuator/health

# Expected response:
# {"status":"UP"}

Step 7: Create Your First Account (Optional)

curl -X POST http://localhost:8081/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "username": "your-username",
    "email": "your-email@example.com",
    "password": "secure-password-here"
  }'

🔌 Environment Variables (.env.example)

The .env.example file is already included in the repository. Copy and configure:

# Database
DB_PASSWORD=your-secure-password-here

# JWT Security
# Generate with: openssl rand -base64 32
JWT_SECRET_KEY=your-32-character-minimum-secret-key-here

# (Optional) Google OAuth
# GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
# GOOGLE_CLIENT_SECRET=your-client-secret
# GOOGLE_REDIRECT_URI=http://localhost:8081/api/auth/google/callback

📦 Build & Deploy

Build for Production

mvn clean package -DskipTests

This generates an executable JAR in target/sgvs-api-0.0.1-SNAPSHOT.jar.

Run the JAR

java -jar target/sgvs-api-0.0.1-SNAPSHOT.jar

With Docker

docker build -t sgvs-api:latest .
docker run -p 8081:8081 \
  -e DB_PASSWORD='your-password' \
  -e JWT_SECRET_KEY='your-secret' \
  sgvs-api:latest

🧪 Testing

Run unit tests:

# Run all tests
mvn test

# Run with coverage
mvn test jacoco:report

Tests cover main services: ProductService, SaleService, CustomerService, ExpenseService.

📚 Documentation & Resources

API Docs: [Swagger UI] (coming soon)
Roadmap: See README.md for complete phases
Project Structure:
- controller — REST Controllers
- src/main/java/com/flick/business/core/service/ — Business logic
- entity — JPA Entities
- repository — Data access

🤝 Contributing

This is a portfolio project. If you find bugs or have suggestions, open an issue or pull request.

📄 License

This project is under the MIT license. See the LICENSE file for details.

👨‍💻 Author

Developed with ❤️ as a modern full-stack business management project.

Frontend (React + Vite): sgvs-ui

Name		Name	Last commit message	Last commit date
Latest commit History 77 Commits
.mvn/wrapper		.mvn/wrapper
docs		docs
src		src
.env.example		.env.example
.gitattributes		.gitattributes
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
architecture.md		architecture.md
mvnw		mvnw
mvnw.cmd		mvnw.cmd
pom.xml		pom.xml
pt_br.md		pt_br.md

Folders and files

Latest commit

History

Repository files navigation