Aplikasi ini merupakan Backend API Service yang dibangun menggunakan Node.js, Express.js, TypeScript, dan PostgreSQL sebagai bagian dari proyek akhir (Capstone Project) program Veteran Tech 2026.
Kosongin hadir sebagai platform "rem digital" dan ruang refleksi bagi Gen Z dan Milenial untuk membangun kebiasaan belanja yang lebih sadar (mindful consumption). Aplikasi ini fokus pada intervensi perilaku sebelum transaksi (melalui Impulse Shield), pelacakan riwayat konsumsi, dan penyediaan wadah aksi nyata melalui Community Challenges untuk mengatasi eco-guilt.
🧾 Informasi Proyek
- Program/Acara: Capstone Project - Veteran Tech 2026
- Tema: SDG 12 (Responsible Consumption) x SDG 9 (Industry, Innovation and Infrastructure)
- Kelompok: Kelompok 1
👥 Anggota Kelompok
| No | Nama Lengkap | Peran / Role |
|---|---|---|
| 1 | Tania Syarofina Aliyah | Product Manager |
| 2 | Jeremia Marco Namara | Product Manager |
| 3 | Nawra Nashiramitha Fawza | Front-End Developer |
| 4 | Andhika Rahman | Front-End Developer |
| 5 | Kemal Satya Wibowo | Back-End Developer |
| 6 | Radya Muhammad Ikmal | Back-End Developer |
| 7 | Prasasti Nurul Septiana | UI/UX Designer |
Project ini dibangun dengan arsitektur modern berbasis Node.js:
- Language: TypeScript
- Framework: Express.js
- Database ORM: Drizzle ORM (dengan PostgreSQL)
- Validation: Zod (Schema-based validation)
- Authentication: JSON Web Token (JWT)
- Job Scheduler: Node-cron (untuk pengingat dan update otomatis)
- API Documentation: OpenAPI/Scalar (direpresentasikan di openapi.yaml)
- Deployment: Railway
Sebelum memulai, pastikan sistem Anda memiliki:
- Node.js v18.x atau lebih tinggi (Download)
- npm v9.x atau lebih tinggi (biasanya disertakan dengan Node.js)
- PostgreSQL v12 atau lebih tinggi (database server lokal atau remote)
- Git untuk cloning repository
Verifikasi instalasi:
node --version # Harus v18.x+
npm --version # Harus v9.x+Berikut adalah peta dari direktori src/:
1 src/
5 ├── middlewares/ # Fungsi perantara (Auth, Error handling, Validation)
6 ├── query/ # Layer akses data (Query SQL mentah/Drizzle)
7 ├── routes/ # Definisi endpoint API dan pemetaan ke controller
8 ├── schemas/ # Definisikan skema Zod untuk validasi data
9 ├── utility/ # Fungsi bantuan (Email, Cron jobs, Custom Error)
Fungsi File-File Penting:
- src/index.ts: Entry point aplikasi. Menjalankan server, menghubungkan rute, dan memulai Cron Jobs.
- src/db/schema.ts: "Single source of truth" untuk struktur tabel database. Semua tabel (Users, Consumptions, Wishlists, dll) didefinisikan di sini.
- src/middlewares/auth.middleware.ts: Menangani verifikasi JWT dan Role-Based Access Control (RBAC).
- src/utility/reminder.cron.ts: Berisi logika otomatisasi yang berjalan di background (misal: mengirim email pengingat harian).
- Aliran Data (Data Flow)
Memahami bagaimana data bergerak dari request user hingga ke database:
- Request: User memanggil endpoint (misal: POST /api/consumption-logs).
- Routing (routes/): Request diterima oleh router. Di sini, middleware validasi dipanggil pertama kali.
- Validation (middlewares/validation.middleware.ts & schemas/): Data di req.body atau req.query diperiksa menggunakan Zod. Jika tidak valid, API langsung mengembalikan error 400.
- Authentication (middlewares/auth.middleware.ts): Jika endpoint diproteksi, middleware akan mengecek token JWT dan menyuntikkan data user ke req.user.
- Controller (controllers/): Jika validasi & auth lolos, controller mengambil alih. Controller bertugas mengolah logika (misal: menghitung sesuatu) tapi tidak melakukan query langsung.
- Query (query/): Controller memanggil fungsi di layer Query. Di sini Drizzle ORM melakukan interaksi dengan database PostgreSQL.
git clone https://github.com/polaariiss/kosongin-backend.git
cd kosongin-backendnpm installSalin .env.example ke .env:
cp .env.example .envKemudian edit .env dan isi nilai-nilai berikut dengan kredensial Anda:
# Database
DATABASE_URL=postgresql://user:password@localhost:5432/kosongin_db
# Cloudinary (untuk upload gambar)
CLOUDINARY_CLOUD_NAME=your_cloud_name
CLOUDINARY_API_KEY=your_api_key
CLOUDINARY_API_SECRET=your_api_secret
# Email Service (Resend)
RESEND_API_KEY=your_resend_api_key
RESEND_SENDER=noreply@kosongin.example.com
# Upload Folders
UPLOAD_CONSUMPTION_FOLDER=consumptions
UPLOAD_CHALLENGE_POSTER_FOLDER=challenges
# Environment
NODE_ENV=development
# Frontend URL (untuk CORS)
FRONTEND_URL=http://localhost:3000
# Admin Special Code
ADMIN_SPECIAL_CODE=your_admin_code
⚠️ Catatan: Jangan commit file.envke repository. Gunakan.env.examplesebagai template.
Jalankan migrasi schema ke database PostgreSQL Anda:
npm run db:push(Alternatif: Jika ingin generate migrasi baru, gunakan npm run db:generate)
Jika ingin mengisi database dengan data dummy untuk testing:
npm run db:seedUntuk development dengan hot reload:
npm run devServer akan berjalan di http://localhost:3000 (atau port lain yang terdefinisi).
Atau untuk production:
npm run build
npm startDokumentasi API tersedia di dua format:
Akses dokumentasi API interaktif di:
http://localhost:3000/api/docs
File lengkap OpenAPI spec tersedia di:
./openapi.yaml
Anda bisa import file ini ke Postman atau tools lainnya untuk testing.
- Buka Postman
- Klik Import → File
- Pilih Postman collection file (jika disediakan di repo)
- Collection akan berisi semua endpoint yang sudah dikonfigurasi
Jika tidak ada pre-made collection:
- Set Base URL:
http://localhost:3000/api - Gunakan dokumentasi OpenAPI di bagian API Documentation
- Untuk endpoint yang memerlukan auth, tambahkan header:
Authorization: Bearer YOUR_JWT_TOKEN
| Command | Deskripsi |
|---|---|
npm run dev |
Jalankan server dalam dev mode dengan hot reload |
npm run build |
Build TypeScript ke JavaScript |
npm start |
Jalankan production build |
npm run lint |
Cek code style dengan ESLint |
npm run format |
Format code dengan Prettier |
npm run db:push |
Sinkronkan schema database |
npm run db:generate |
Generate migrasi database baru |
npm run db:seed |
Seed database dengan data dummy |
Vercel: https://kosongin.vercel.app
Railway: https://postgres-production-53aa.up.railway.app
Pastikan environment variables berikut sudah dikonfigurasi di platform deployment (Railway/Vercel/etc):
DATABASE_URL→ Production PostgreSQL URLNODE_ENV=productionCLOUDINARY_*→ Production credentialsRESEND_API_KEY→ Production email service keyFRONTEND_URL→ Production frontend URL- Semua variabel lainnya sesuai dengan
.env.example
# Ubah port di src/index.ts atau set environment variable PORT
PORT=3001 npm run dev- Pastikan PostgreSQL server berjalan
- Cek
DATABASE_URLdi.envsudah benar - Verifikasi credentials database
npm install -g tsx # Install tsx globally
npm run devUntuk reporting bugs atau request features, buka issue di repository:
https://github.com/polaariiss/kosongin-backend/issues