From a53568da8fd897821f7f7867c2824b3fbf784fa5 Mon Sep 17 00:00:00 2001 From: amaliadwiy Date: Fri, 24 Apr 2026 15:49:57 +0800 Subject: [PATCH] docs: split CLAUDE.md into focused reference files Move architecture, env vars, and deployment details into .claude/ subdocs referenced via @-imports, keeping CLAUDE.md to commands and pointers only. Co-Authored-By: Claude Sonnet 4.6 --- .claude/ARCHITECTURE.md | 43 +++++++++++++++++++++++++++++++ .claude/DEPLOYMENT.md | 5 ++++ .claude/ENV.md | 12 +++++++++ CLAUDE.md | 56 +++-------------------------------------- 4 files changed, 63 insertions(+), 53 deletions(-) create mode 100644 .claude/ARCHITECTURE.md create mode 100644 .claude/DEPLOYMENT.md create mode 100644 .claude/ENV.md diff --git a/.claude/ARCHITECTURE.md b/.claude/ARCHITECTURE.md new file mode 100644 index 0000000..0b126a5 --- /dev/null +++ b/.claude/ARCHITECTURE.md @@ -0,0 +1,43 @@ +# 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 + +All DB access goes through the Prisma client singleton in `src/lib/prisma.ts`. Schema at `prisma/schema.prisma` (40+ models). Migrations in `prisma/migrations/`. + +## State Management + +- **Hookstate** (`@hookstate/core` + `@hookstate/localstored`) — client-side global state with localStorage persistence +- **Iron-session** — server-side session management / auth +- **Jose** — JWT handling + +## UI Stack + +- **Mantine 7** — primary UI library (components, forms, modals, notifications, charts, dates) +- **Tailwind CSS** — utility classes, used alongside Mantine +- **PostCSS** — configured with Mantine preset (`postcss.config.mjs`) + +## Real-time & Notifications + +- **Firebase FCM** (`src/lib/firebase/`) — mobile push notifications +- **Web Push + VAPID keys** (`src/lib/usePushNotifications.ts`) — browser push +- **wibu-realtime** (custom library) — WebSocket-based real-time updates + +## User Roles + +Five roles with distinct access levels (see `PANDUAN PENGGUNAAN.md`): + +1. **Super Admin** — full system access +2. **Admin Desa** — village-level administration +3. **Ketua Divisi** — division leader +4. **Anggota Divisi** — division member +5. **Warga/Perangkat Desa** — village resident/official diff --git a/.claude/DEPLOYMENT.md b/.claude/DEPLOYMENT.md new file mode 100644 index 0000000..ae618c3 --- /dev/null +++ b/.claude/DEPLOYMENT.md @@ -0,0 +1,5 @@ +# 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). diff --git a/.claude/ENV.md b/.claude/ENV.md new file mode 100644 index 0000000..a1b370d --- /dev/null +++ b/.claude/ENV.md @@ -0,0 +1,12 @@ +# 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 | diff --git a/CLAUDE.md b/CLAUDE.md index 378917c..e0a9a91 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -20,62 +20,12 @@ 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`): -1. **Super Admin** — full system access -2. **Admin Desa** — village-level administration -3. **Ketua Divisi** — division leader -4. **Anggota Divisi** — division member -5. **Warga/Perangkat Desa** — village resident/official +See @.claude/ARCHITECTURE.md ## 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 | +See @.claude/ENV.md ## 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). +See @.claude/DEPLOYMENT.md -- 2.49.1