A portfolio-quality full-stack community platform for free item sharing, second-hand trading, and wanted-item requests. ShareLoop connects neighbors to promote local circular economy, reduce waste, and build sustainable communities.
| Layer | Technology | Version | Description |
|---|---|---|---|
| Backend | Spring Boot | 3.5.16 | REST API built on Java 17, Spring Web, Data JPA, Actuator & Validation |
| Frontend | React + TypeScript + Vite | 19.x / Vite 8.x | Modern responsive client with custom design system and type safety |
| Database | PostgreSQL | 16-Alpine | Relational persistence with volume isolation and health checks |
| Build & Tooling | Maven Wrapper & npm | Wrapper 3.3.4 | Consistent cross-platform builds without global CLI dependencies |
| DevOps | Docker Compose | 5.x specification | Containerized local PostgreSQL service with localhost port binding |
Shareloop/
├── backend/ # Spring Boot REST API application
│ ├── .mvn/wrapper/ # Maven Wrapper configuration & properties
│ ├── src/ # Java source and test suites
│ ├── mvnw / mvnw.cmd # Cross-platform Maven Wrapper executables
│ └── pom.xml # Backend dependencies & build setup
├── frontend/ # React + TypeScript + Vite web client
│ ├── src/ # UI components, styles, and assets
│ ├── package.json # Frontend scripts and dependencies
│ └── vite.config.ts # Vite bundler & backend API proxy configuration
├── docs/ # Project documentation and architecture specs
│ └── README.md
├── docker-compose.yml # Local development PostgreSQL service
├── .env.example # Environment variable template for local dev
├── .gitignore # Git ignore rules for Java, Node, IDEs, and environments
└── README.md # Repository documentation
- Java: Temurin OpenJDK 17+ (Maven CLI not required; Maven Wrapper is included)
- Node.js: v20+ (Node v24 and npm v11 verified)
- Docker & Docker Compose: For running the local PostgreSQL container
Copy the sample environment file to create your local .env:
cp .env.example .envStart the containerized PostgreSQL service:
docker compose up -dThe database port is bound to 127.0.0.1:5432 with credentials defined in .env.example.
Navigate to the backend/ directory and start the Spring Boot application using Maven Wrapper:
- Windows:
cd backend .\mvnw.cmd spring-boot:run
- macOS / Linux:
cd backend ./mvnw spring-boot:run
API health status is available at:
- Service Health:
http://localhost:8080/api/health - Actuator Health:
http://localhost:8080/actuator/health
To populate realistic, fictional Vietnamese listings for local Explore page and UI testing, explicitly opt in via the dev profile and APP_SEED_ENABLED=true:
- Windows (PowerShell):
$env:APP_SEED_ENABLED="true" .\mvnw.cmd spring-boot:run -Dspring-boot.run.profiles=dev
- macOS / Linux:
APP_SEED_ENABLED=true ./mvnw spring-boot:run -Dspring-boot.run.profiles=dev
Security Note: Demo seeding is disabled by default across all environments and is strictly refused by the application under
prod,production, andstagingprofiles, even ifAPP_SEED_ENABLEDis accidentally set.
In a separate terminal, navigate to the frontend/ directory, install dependencies, and launch the dev server:
cd frontend
npm install
npm run devOpen http://localhost:5173 in your browser. API requests to /api are automatically proxied to http://localhost:8080.
ShareLoop uses stateless JWT Bearer token authentication signed via HMAC-SHA256 (HS256) and BCrypt password hashing.
Environment variables (configured in .env / application.yml):
JWT_SECRET: Secret key for signing tokens (minimum 32 characters / 256 bits).JWT_EXPIRATION_MS: Access token lifetime in milliseconds (default:86400000= 24 hours).CORS_ALLOWED_ORIGINS: Comma-separated list of allowed origins (default:http://localhost:5173,http://localhost:3000).
POST /api/v1/auth/register (Public)
curl -X POST http://localhost:8080/api/v1/auth/register \
-H "Content-Type: application/json" \
-d '{
"displayName": "Linh Nguyen",
"email": "linh.nguyen@example.com",
"password": "Password123!"
}'Response (201 Created):
{
"id": "c1f7b49e-711a-4fa0-863a-4418659dca21",
"displayName": "Linh Nguyen",
"email": "linh.nguyen@example.com",
"role": "USER",
"status": "ACTIVE",
"createdAt": "2026-10-20T07:30:00Z",
"accessToken": "eyJhbGciOiJIUzI1NiJ9...",
"tokenType": "Bearer"
}POST /api/v1/auth/login (Public)
curl -X POST http://localhost:8080/api/v1/auth/login \
-H "Content-Type: application/json" \
-d '{
"email": "linh.nguyen@example.com",
"password": "Password123!"
}'Response (200 OK):
{
"id": "c1f7b49e-711a-4fa0-863a-4418659dca21",
"displayName": "Linh Nguyen",
"email": "linh.nguyen@example.com",
"role": "USER",
"status": "ACTIVE",
"createdAt": "2026-10-20T07:30:00Z",
"accessToken": "eyJhbGciOiJIUzI1NiJ9...",
"tokenType": "Bearer"
}GET /api/v1/auth/me (Protected - Requires Bearer Token)
curl -X GET http://localhost:8080/api/v1/auth/me \
-H "Authorization: Bearer <your_access_token>"Response (200 OK):
{
"id": "c1f7b49e-711a-4fa0-863a-4418659dca21",
"displayName": "Linh Nguyen",
"email": "linh.nguyen@example.com",
"phoneNumber": null,
"role": "USER",
"status": "ACTIVE",
"createdAt": "2026-10-20T07:30:00Z",
"updatedAt": "2026-10-20T07:30:00Z"
}Run unit tests and verification with Maven Wrapper:
cd backend
.\mvnw.cmd clean testTo build the executable production JAR:
cd backend
.\mvnw.cmd clean packageRun linter and production build:
cd frontend
npm run lint
npm run buildValidate compose configuration:
docker compose config