https://github.com/faisalaffan/community-waste-collection-api
REST API for community waste collection — households, pickups, payments, and reports. Built with Go Fiber
https://github.com/faisalaffan/community-waste-collection-api
atlas docker fiber ghcr go golang gorm minio openapi postgresql rest-api swagger waste-management
Last synced: 8 days ago
JSON representation
REST API for community waste collection — households, pickups, payments, and reports. Built with Go Fiber
- Host: GitHub
- URL: https://github.com/faisalaffan/community-waste-collection-api
- Owner: faisalaffan
- License: mit
- Created: 2026-06-16T18:10:38.000Z (16 days ago)
- Default Branch: dev
- Last Pushed: 2026-06-17T06:15:22.000Z (16 days ago)
- Last Synced: 2026-06-17T07:15:56.445Z (15 days ago)
- Topics: atlas, docker, fiber, ghcr, go, golang, gorm, minio, openapi, postgresql, rest-api, swagger, waste-management
- Language: Go
- Homepage: https://waste-collection.faisalaffan.com
- Size: 3.46 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 4
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Citation: CITATION.cff
- Codeowners: CODEOWNERS
- Security: SECURITY.md
- Support: SUPPORT.md
- Authors: AUTHORS.md
Awesome Lists containing this project
README
Community Waste Collection API
REST API + Admin Dashboard for community waste collection — households, pickups, payments, and reports.
## Screenshots
## Coverage
243 tests — 100% statement coverage across all 11 packages.
Every repository, service, handler, middleware, storage, and router function is tested.
Covered: config, handler, middleware, repository, router, service, worker, database, response, storage.
## Architecture
```
cmd/server/ Entry point, DI wiring, graceful shutdown
internal/
config/ Viper .env loader
domain/ GORM models, DTOs, type constants
handler/ HTTP handlers (Fiber v3)
service/ Business logic
repository/ Data access (GORM)
middleware/ Rate limiter
router/ Routes + Swagger UI
worker/ Background goroutines
pkg/
database/ GORM connection helper
storage/ MinIO/S3 client
response/ JSON response envelope
migrations/ Atlas HCL schema + config
docs/ Swagger spec
web/ Vue 3 + Tailwind SPA
assets/ Logo + banner
```
**Stack**: Go 1.26 · Fiber v3 · GORM · PostgreSQL 16 · Atlas · Viper · MinIO · Docker · Vue 3 CDN · Tailwind CDN
## Technical Decisions
Setiap keputusan teknis di project ini punya alasan — bukan sekadar preferensi. Dokumen lengkap: **[docs/technical-decisions.md](docs/technical-decisions.md)**.
| Decision | Why |
|---|---|
| **Go + Fiber v3** | Fasthttp-based, throughput 2-10x Gin, zero alloc router |
| **Clean Architecture** | Handler → Service → Repository: testable, replaceable, no circular deps |
| **GORM** | Multi-driver (SQLite test / PostgreSQL prod), auto-migration, less boilerplate |
| **PostgreSQL + UUID PK** | Distributed-safe, no ID collision, compatible with horizontal scaling |
| **Atlas (declarative)** | Write desired state, not migration steps — safety with `--dry-run` |
| **MinIO / S3** | Stateless app, same API dev→prod, DB not burdened with binary data |
| **Docker multi-service** | Production parity, health-check gated startup, volume persistence |
| **Vue 3 + Tailwind CDN** | Zero build step, no `node_modules`, Docker image stays ~30MB |
| **Background goroutine** | Self-contained worker, graceful via context, no external scheduler |
| **Manual DI** | Explicit dependency graph, compile-time safety, no code generation |
| **Envelope response** | Client-side consistency — single `status` check for all API outcomes |
| **243 tests · 100% coverage** | SQLite in-memory driver, mock-ready interfaces, layer isolation |
## Quick Start
Prerequisites: Go 1.26+, Docker, [Atlas CLI](https://atlasgo.io/getting-started).
```bash
git clone https://github.com/faisalaffan/community-waste-collection-api.git
cd community-waste-collection-api
cp .env.example .env
make docker-up
make schema-apply
```
Admin Dashboard → `http://localhost:8080` · Swagger → `http://localhost:8080/swagger` · Postman → [Collection](assets/postman_collection.json)
**Live Demo**: [waste-collection.faisalaffan.com](https://waste-collection.faisalaffan.com) · [Swagger API](https://waste-collection.faisalaffan.com/swagger)
## Video Tutorial
Watch Video Tutorial →
Architecture walkthrough, API demo, deployment guide.
## API Reference
Base: `/api`. Response envelope:
- **Success**: `{"status":"success","data":{}}`
- **List**: `{"status":"success","data":[],"pagination":{"page":1,"per_page":10,"total":42,"total_pages":5}}`
- **Error**: `{"status":"error","error":{"code":"NOT_FOUND","message":"..."}}`
- **Validation**: `{"status":"fail","error":{"code":"VALIDATION_ERROR","message":"...","details":[]}}`
### Households
```
POST /api/households Create {owner_name, address}
GET /api/households List ?page=1&per_page=10
GET /api/households/:id Get
PUT /api/households/:id Update {owner_name, address}
DELETE /api/households/:id Delete
```
### Waste Pickups
```
POST /api/pickups Create {household_id, type, safety_check}
GET /api/pickups List ?status=&household_id=&page=1&per_page=10
PUT /api/pickups/:id Update {type, safety_check}
DELETE /api/pickups/:id Delete
PUT /api/pickups/:id/schedule Schedule {pickup_date}
PUT /api/pickups/:id/complete Complete (auto-generates payment)
PUT /api/pickups/:id/cancel Cancel
```
Types: `organic`, `plastic`, `paper`, `electronic`. Rate limit: 30 req/min.
### Payments
```
POST /api/payments Create
GET /api/payments List ?status=&household_id=&page=1&per_page=10
PUT /api/payments/:id/confirm Confirm (multipart: proof_file)
```
### Reports
```
GET /api/reports/waste-summary Pickup aggregation by type
GET /api/reports/payment-summary Payment totals (pending, paid, failed) + revenue
GET /api/reports/households/:id/history Pickup + payment history per household
```
### Files
```
GET /api/files/proof/:paymentID Serve payment proof image (proxied from S3)
```
## Business Rules
- Pending payment → blocked from new pickup (409)
- Only `pending` pickups can be scheduled (409)
- Electronic waste requires `safety_check: true` (422)
- Organic pickups pending >3 days auto-canceled
- Completing pickup auto-generates payment (Rp 50k organic/plastic/paper, Rp 100k electronic)
- Payment confirmation requires S3/MinIO proof upload
## Database
Schema managed by [Atlas](https://atlasgo.io) (`migrations/schema.pg.hcl`).
```bash
make schema-apply # Apply
make schema-diff # Preview (dry-run)
make schema-inspect # Pull from DB
make schema-dump # Export DDL to migrations/schema.sql
```
Tables: `households`, `waste_pickups`, `payments` — UUID PKs, FK with CASCADE, B-tree indexes.
## Testing
243 tests · 100% coverage.
```bash
make test # go test ./... -v
make coverage # profile + summary
make coverage-html # browser report
```
## Makefile
```bash
make build # Build binary
make dev # go run
make test # Run tests
make lint # go vet
make docker-up # Start all services
make docker-down # Stop all services
make swagger-clean # Regenerate swagger
make schema-apply # Apply Atlas schema
make schema-dump # Export DDL to SQL
make all # lint + test + build
```