Anmategra App

Build With T3 Stack

Tentang Anmategra

Anmategra platform manajemen data kemahasiswaan/lembaga di ITB. Fungsi utama:

• Lembaga & Keanggotaan — data lembaga, anggota, posisi/divisi, request asosiasi anggota ke lembaga
• Kegiatan/Event — pengelolaan event, panitia, pendaftaran
• Profil — profil mahasiswa & lembaga, pemetaan profil ke kegiatan/lembaga
• Rapor & Best Staff — penilaian lembaga, riwayat best staff per periode
• Role-based access — 3 peran: admin, lembaga, mahasiswa

Tech stack: T3 Stack (Next.js, tRPC, Drizzle ORM, NextAuth, Tailwind), PostgreSQL.

Setup untuk Developer Baru

Prasyarat

1. Node.js v20+
2. npm 10+ (packageManager di package.json pin ke [email protected])
3. PostgreSQL aktif di lokal

Instalasi

git clone <repo-url>
cd anmategra-app
cp .env.example .env
npm install

Isi .env, minimal DATABASE_URL bener, contoh:

DATABASE_URL="postgresql://postgres:password@localhost:5432/anmategra"

husky prepare hook otomatis jalan pas npm install (setup lint-staged pre-commit).

Setup Database

Opsi A — manual:

psql -U postgres
CREATE DATABASE anmategra;
\q

npm run db:push

Opsi B — pakai Docker (lihat scripts/start-database.sh):

./scripts/start-database.sh
npm run db:push

Opsi C — app + database sekaligus di Docker (compose.local.yml):

docker compose -f compose.local.yml up --build

• Postgres 15 jalan di port host 5433, app (next dev, hot reload) di 3000. Ubah lewat APP_PORT / DB_PORT.
• Kalau ada anmategra.dump di folder induk repo, dump itu dipulihkan saat pertama kali jalan, lalu db:migrate menyusulkan migrasi yang belum ada. Lokasi lain: set DB_DUMP_DIR / DB_DUMP_FILE.
• Kredensial OAuth boleh dibiarkan kosong (diisi placeholder), tetapi login baru berfungsi dengan kredensial sungguhan di .env.
• Masuk tanpa OAuth: docker compose -f compose.local.yml exec app node docker/local/dev-login.mjs <admin|lembaga|mahasiswa> [email], lalu tempel baris yang dicetak ke console browser. Dump tidak berisi admin, jadi ubah dulu role satu user di database lokal.
• Ulang dari dump: docker compose -f compose.local.yml down -v.

Perintah db lain yang tersedia:

• npm run db:generate — generate migration dari schema (drizzle-kit generate)
• npm run db:migrate — jalanin migration (drizzle-kit migrate)
• npm run db:studio — buka Drizzle Studio buat liat data
• npm run db:seed — generate csv + seed database (dev only)
• npm run db:seed-lembaga — seed akun lembaga resmi dari src/server/db/seeding/data/lembaga-official.csv (idempotent)
• npm run db:seed-mahasiswa -- --file <csv> — impor mahasiswa (misalnya satu angkatan baru); hanya menambah, format di src/server/db/seeding/data/README.md
• npm run db:backfill-lembaga-descriptions — lengkapi deskripsi lembaga yang kosong
• npm run db:refresh-lembaga — jalanin scripts/refresh-lembaga.sh (refresh data lembaga dari sumber resmi)
• npm run db:summarize-lembaga — jalanin scripts/km-summarize.ts (ringkas profil lembaga)
• npm run db:clear — kosongin database

Menjalankan Project

npm run dev

Buka http://localhost:3000.

Script lain:

• npm run build — build production
• npm run start — jalanin hasil build
• npm run lint — cek lint (ESLint, eslint.config.mjs). Pelanggaran lama dicatat di eslint-suppressions.json; pelanggaran baru membuat CI gagal. Setelah memperbaiki pelanggaran lama, jalankan npm run lint:prune dan commit perubahan file itu.
• npm run typecheck — cek tipe TypeScript (tsc --noEmit)
• npm test — jalankan tes otomatis (Vitest); lihat Menjalankan Tes. npm run test:watch mengulang tes setiap berkas berubah.
• npm run docs — regenerate dokumentasi API & database di docs/api/

Menjalankan Tes

Tes memakai Vitest dan PostgreSQL asli, bukan mock, supaya aturan akses diuji terhadap skema yang sama dengan produksi.

npm test

• Database uji terpisah dari database pengembangan. Alamatnya dari TEST_DATABASE_URL; bawaannya postgresql://postgres:password@localhost:5432/anmategra_test. Nama database wajib memuat kata test; kalau tidak, tes menolak jalan karena tiap kasus mengosongkan tabel.
• Sebelum tes pertama, src/test/global-setup.ts membuat database itu bila belum ada (dari template0) dan menerapkan semua migrasi di drizzle/. Run berikutnya melewati migrasi yang sudah diterapkan.
• Berkas tes diberi akhiran .test.ts dan diletakkan di samping kodenya. Helper database dan pabrik data ada di src/test/test-db.ts.
• Tes tidak butuh .env lengkap: kode yang diuji tidak boleh memuat ~/env. Prosedur yang butuh sesi atau NextAuth sebaiknya diuji lewat logika yang dipisah, seperti src/server/api/access.ts.
• CI menjalankan npm test pada job Test dengan layanan PostgreSQL 15.

Login Microsoft (SSO ITB)

Mahasiswa login dengan akun @mahasiswa.itb.ac.id lewat Microsoft Entra ID milik ITB. Anmategra punya app registration sendiri di directory ITB:

• Supported account types: Accounts in any organizational directory (multitenant).
• Redirect URI (platform Web): https://anmategra.com/api/auth/callback/azure-ad, ditambah http://localhost:<APP_PORT>/api/auth/callback/azure-ad untuk lokal.
• Client secret dibuat di Certificates & secrets lalu diisi ke AZURE_AD_CLIENT_SECRET. Secret punya tanggal kedaluwarsa: catat tanggalnya dan perbarui sebelum lewat. Secret yang kedaluwarsa membuat login Microsoft gagal dengan ?error=OAuthCallback.
• AZURE_AD_TENANT_ID = db6e1183-4c65-405c-82ce-7cd53fa6e9dc (directory ITB). Token dari tenant lain ditolak, walaupun email-nya berakhiran @mahasiswa.itb.ac.id.
• Pastikan app registration punya minimal 2 owner supaya aksesnya tidak hilang saat pengurus berganti.

This is the beginning of the README. Read the rest at the original. Read the full README ↗