CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

# Development
bun install                  # Install dependencies
bun run dev                  # Dev server with experimental HTTPS (localhost:3000)
bun run build                # Production build
bun run start                # Start production server
bun run lint                 # Run ESLint

# Database
npx prisma migrate dev       # Run/create migrations
npx prisma db seed           # Seed with initial data
npx prisma generate          # Regenerate Prisma client after schema changes

Architecture

Sistem Desa Mandiri is a village administration platform built on Next.js 14 (App Router) with PostgreSQL.

Key Layers

src/app/(application)/ — Auth-protected pages grouped by feature (announcement, division, project, discussion, member, profile, home, group)
src/app/(auth)/ — Login/register pages
src/app/api/ — REST API endpoints; subdirectories map to resource types (/api/announcement, /api/project, /api/task, etc.). Mobile-specific endpoints live under /api/mobile/
src/module/ — Business logic modules, one per feature (19 modules). Each module contains hooks, components, and API call functions for that domain
src/lib/ — Shared utilities: Prisma client singleton (prisma.ts), Firebase init, route definitions (routes.ts), push notification hooks

Data Access Pattern

All DB access goes through the Prisma client singleton in src/lib/prisma.ts. Prisma schema is at prisma/schema.prisma (40+ models). Migrations live in prisma/migrations/.

State Management

Hookstate (@hookstate/core + @hookstate/localstored) for client-side global state with localStorage persistence
Iron-session for server-side session management / auth
Jose for JWT handling

UI Stack

Mantine 7 is the primary UI library (components, forms, modals, notifications, charts, dates, etc.)
Tailwind CSS for utility classes — used alongside Mantine
PostCSS configured with Mantine preset (postcss.config.mjs)

Real-time & Notifications

Firebase FCM (src/lib/firebase/) for mobile push notifications
Web Push + VAPID keys (src/lib/usePushNotifications.ts) for browser push
wibu-realtime (custom library) for WebSocket-based real-time updates

User Roles

Five roles with distinct access levels (see PANDUAN PENGGUNAAN.md):

Super Admin — full system access
Admin Desa — village-level administration
Ketua Divisi — division leader
Anggota Divisi — division member
Warga/Perangkat Desa — village resident/official

Environment Variables

Copy .env.example to .env. Required variables:

Variable	Purpose
`DATABASE_URL`	PostgreSQL connection string
`GOOGLE_PROJECT_ID`, `GOOGLE_CLIENT_EMAIL`, `GOOGLE_PRIVATE_KEY`	Firebase Admin SDK (FCM)
`NEXT_PUBLIC_VAPID_PUBLIC_KEY`, `VAPID_PRIVATE_KEY`	Web Push
`WS_APIKEY`	WebSocket/file storage API key
`WIBU_REALTIME_KEY`	Real-time communication
`FCM_KEY`	Firebase Cloud Messaging

Deployment

Docker images are built via .github/workflows/publish.yml and pushed to GHCR (ghcr.io). Portainer redeploys via .github/workflows/re-pull.yml. Supports dev, stg, and prod stacks.

The Dockerfile uses a two-stage build: Bun builder → Bun runner (non-root user, port 3000).

3.4 KiB Raw Blame History