robotik-pnp

Imported from zakyrmh/robotik-pnp (AGENTS.md). Install upstream with npx skills add zakyrmh/robotik-pnp. Copyright stays with the author.

Next.js: ALWAYS read docs before coding

Before executing any Next.js work, locate and read the relevant documentation in node_modules/next/dist/docs/ or using the context tools. Your pre-training may be outdated — the current docs and source specifications are the ground truth.

1. Project Overview & Identity

• Project Name: Student Activity Unit Management System — UKM Robotik Politeknik Negeri Padang (Sistem Informasi Manajemen UKM Robotik PNP)
• Domain: SaaS Web Application for organizational governance, recruitment pipelines, laboratory shift rotations, event presence, disciplinary tracking, and administrative audit trails.
• Architectural Paradigm: Server-First Fullstack SaaS using Next.js 16 (App Router, no src/ directory), React 19, Supabase (PostgreSQL + Auth SSR + Storage), Tailwind CSS v4, Upstash Redis, and Cloudflare Turnstile.
• Language & Standards: TypeScript in strict mode (strict: true), ESLint 9 (Flat Config), Prettier, Conventional Commits.

2. Exact Tech Stack & Dependency Matrix

3. Role-Based Access Control (RBAC) & Permission Matrix

The system enforces strict access boundaries across 5 core roles. All Route Handlers, Server Actions, and UI Views must validate these roles against server-verified sessions:

Operational Workflow RBAC Matrix (docs/04-process-view/workflow-documentation.md)

4. Project Architecture & Codebase Map

robotik-pnp/
├── app/                              # Next.js App Router (Server-First by default)
│   ├── (auth)/                       # Auth routes (login, register, forgot/update password, verify)
│   ├── (marketing)/                  # Public landing pages (artikel, divisi, prestasi, keanggotaan, profil)
│   ├── (onboarding-flow)/            # Post-registration onboarding (waiting, rejected, deleted)
│   ├── (private)/                    # Protected application portals (RBAC guarded)
│   │   ├── dashboard/                # Main role-specific dashboard
│   │   ├── kegiatan/                 # Activity sessions & general attendance
│   │   ├── kegiatan-absensi-caang/   # Candidate dynamic QR scan & presence management
│   │   ├── piket/                    # Laboratory shift scheduling & verification
│   │   ├── manajemen-caang/          # Recruitment applicant evaluation
│   │   ├── manajemen-kelompok/       # Mentorship group assignments
│   │   ├── manajemen-struktur/       # Organizational leadership tree
│   │   ├── manajemen-akun/           # User administration
│   │   ├── audit-log/                # Immutable security & mutation logs
│   │   └── kedisiplinan/             # Points, disciplinary records & sanctions (SP)
│   ├── api/                          # Edge/webhook route handlers ONLY (no form mutations)
│   ├── globals.css                   # Tailwind CSS v4 @theme design tokens
│   └── layout.tsx                    # Root layout with Toast, Sentry, and Analytics providers
├── components/                       # UI Components (shadcn/ui primitives & feature atomic units)
│   └── ui/                           # Reusable base components (buttons, dialogs, tables, cards)
├── hooks/                            # Custom client hooks (QR scanning, camera, media)
├── lib/
│   ├── actions/                      # Secure Next.js Server Actions ('use server')
│   ├── repositories/                 # Data access layer & domain services
│   ├── schemas/                      # Zod validation schemas for all inputs
│   ├── supabase/                     # Supabase client factories
│   │   ├── server.ts                 # createServerClient factory for RSC & Server Actions
│   │   ├── client.ts                 # createBrowserClient factory for Client Components
│   │   └── proxy.ts                  # Middleware session gatekeeper
│   ├── redis.ts                      # Upstash Redis & RateLimiter instances
│   ├── turnstile.ts                  # Cloudflare Turnstile token verification
│   └── utils.ts                      # cn() helper (clsx + tailwind-merge)
├── types/                            # Global TypeScript types & Supabase generated database types
├── docs/                             # Full architectural & compliance documentation (01 to 08)
└── supabase/
    └── migrations/                   # Tracked SQL database migrations with strict RLS

5. Core Business Logic & Domain Constraints

AI Agents must strictly adhere to the functional requirements of all core modules:

1. Authentication & Identity Parity:

   • During candidate signup and profile creation, the generated user profile id (UUID) MUST match the corresponding registration document identifier 1:1.
   • Never trust client-supplied user_id; always resolve identity via supabase.auth.getUser().

2. Open Recruitment (Oprec) & Progression:

   • Multi-phase flow: Registration & Document Screening $\rightarrow$ Interview (Org & Technical) $\rightarrow$ Divisional Allocation $\rightarrow$ Training & Robotics Internship $\rightarrow$ Plenary Evaluation $\rightarrow$ Official Member Decree (SK).

3. Digital Attendance & Dynamic QR Rotation:

   • Formal activities generate a dynamic QR code token (ukmrobotik:qr:session) refreshed every 30 seconds to prevent unauthorized screenshot sharing.
   • Attendance scoring: Hadir (+10), Late Tolerance (+7.5), Late >15m (+5), Izin/Sakit (+5), Alpha (0).
   • Point infractions trigger automatic Draft Disciplinary Warning Letters (SP) reviewed by admin-komdis.

4. Laboratory Shift Duty (Manajemen Piket):

   • Shift rotations are scheduled by admin-komdis.
   • Automated H-1 reminder triggers at 18:00 WIB via scheduled cron.
   • Shift personnel must upload clean lab photo proof to the private piket-proofs bucket.
   • Missed shift (Alpha) or rejected proof incurs an automatic fine of Rp10.000 and penalty points.

5. Immutable Audit Trails (Multi-Layer Immutability):

   • Every administrative write or mutation (INSERT, UPDATE, DELETE) by super-admin, admin-or, or admin-komdis MUST create an immutable log record in public.audit_logs.
   • The public.audit_logs table is protected by a PostgreSQL trigger preventing any UPDATE or DELETE.
   • Log entries adhere to Schema JSON v2.0 (timestamp UTC ISO 8601, actor ID, action, target entity, details, correlation ID).
   • Personal Identifiable Information (PII) must be masked (NIM 210109****, Phone 0812-****-5678, Email u***r@domain.com). Raw passwords and auth tokens are forbidden in logs.

6. Frontend & UI/UX Design System (DESIGN.md Standard)

The application follows the Minimalist Soft (Light) design aesthetic:

Color Palette (70-20-10 Rule)

• 70% Neutral: Canvas White (#ffffff / --color-canvas) and Surface Muted (#f8fafc / --color-surface) for backgrounds, cards, and zebra-striped tables. Border is 1px --color-border (#e5e7eb).
• 20% Primary: Soft Navy (#3b5b84 / --color-primary), Hover (#2f4a6d / --color-primary-hover), Soft Tint (#eaf1f8 / --color-primary-soft) for brand identity, primary buttons, and key headings.
• 10% Accent: Soft Orange PNP (#f0975a / --color-accent), Deep Accent (#9a5b30 / --color-accent-deep), Tint (#fdeee1 / --color-accent-soft) used sparingly for status badges, highlights, and alerts.

Typography

• Heading Font: Plus Jakarta Sans (--font-display), Semibold (600), tracking-tight.
• Body Font: Inter (--font-body), Regular (400) for text, Medium (500) for labels/buttons, Semibold (600) for table headers.
• Code/Technical Data: System monospace (--font-mono / ui-monospace) for IDs, scores, and tokens.
• Fluid Font Scale: Configured using clamp() in CSS for seamless responsiveness across mobile and desktop.

Touch Targets & Accessibility

• Interactive elements (buttons, inputs, links, dropdown triggers) must have a minimum touch target height of $44\text{ px}$ (min-h-[44px]).
• Reusable UI styling must always use the cn() helper (@/lib/utils).

7. AI Code Generation & Modern Stack Rules

Next.js 16 & React 19 Standards

1. Server Components Default: All files in app/ and components/ are React Server Components (RSC) unless interactive hooks (useState, useEffect, useActionState) or browser APIs are required.
2. Interleaving Pattern: Keep page.tsx as an RSC for direct Supabase data fetching. Isolate interactive elements into small, client-leaf components marked with 'use client'.
3. Async params and searchParams: Always await params and searchParams in Next.js 16:

   export default async function Page({
     params,
   }: {
     params: Promise<{ id: string }>;
   }) {
     const { id } = await params;
     return <div>ID: {id}</div>;
   }

4. React 19 ref Props: DO NOT USE forwardRef (deprecated in React 19). Pass ref as a standard prop:

   export function Input({
     ref,
     ...props
   }: React.ComponentPropsWithRef<"input">) {
     return <input ref={ref} {...props} />;
   }

5. Form States: Use React 19 useActionState and useFormStatus for managing Server Action pending and error states.

Data Mutation & Server Actions

1. Mutations via Server Actions: All form submissions and data modifications MUST use Server Actions ('use server'). Do not create ad-hoc API routes for standard form submissions.
2. Input Validation: Every Server Action must validate incoming payloads using a Zod schema (lib/schemas/*) before performing database queries.
3. Cache Revalidation: Always invoke revalidatePath('/path') or revalidateTag('tag-name') upon successful mutation.
4. Structured Return Types: Always return typed objects:

   export type ActionResult<T = unknown> =
     | { success: true; data: T; message?: string }
     | {
         success: false;
         error: string;
         fieldErrors?: Record<string, string[]>;
       };

Supabase SSR Conventions

1. Client Boundary Separation:
   • Server-side (RSC, Route Handlers, Server Actions): import { createClient } from "@/lib/supabase/server".
   • Client-side (Client Components): import { createClient } from "@/lib/supabase/client".
   • NEVER interchange or import server Supabase factories into client components.
2. Authentication Verification: Always call supabase.auth.getUser(). NEVER use supabase.auth.getSession() on the server due to JWT spoofing vulnerabilities.
3. Storage Uploads: Compress images using browser-image-compression on the client before uploading to Supabase Storage. Enforce strict mime-type and size limits.

Tailwind CSS v4 Rules

1. CSS-First Theme Config: All custom colors, font families, and tokens are declared in app/globals.css using @theme.
2. DO NOT CREATE tailwind.config.js. Tailwind v4 ignores JS config files.

8. Available Agent Skills & References Index

AI Agents should reference and execute the specialized skills installed in .agents/skills/:

9. Quality Assurance, Testing & Git Workflow

• Testing Framework: Vitest (npm run test), React Testing Library, and jsdom.
• Property-Based Testing: fast-check for testing complex algorithms (e.g., presence point calculations, fee generators).
• Quality Gate: Minimum test coverage threshold is strictly $70%$.
• Pre-commit Automation: Husky + lint-staged runs eslint --fix and prettier --write.
• Commit Standard: Conventional Commits (feat:, fix:, docs:, style:, refactor:, test:, chore:). Enforced by @commitlint/cli.
• Pre-PR Verification: Run npm run typecheck, npm run lint, and npm run test before submitting changes.

10. Strict Anti-Patterns & Banned Practices (AI Don'ts)

11. Integrasi Memori Jangka Panjang (Obsidian Vault)

Untuk mempertahankan context awareness lintas sesi terminal, AI Agent diinstruksikan untuk menggunakan Obsidian Vault agents_brain sebagai media penyimpanan memori jangka panjang (Long-term Memory).

11.1 Lokasi Direktori Vault

• Path Utama (Absolute): ~/Documents/agents_brain/
• Sub-folder Memori: ~/Documents/agents_brain/02_agent_memory/
• Sub-folder Referensi/Knowledge: ~/Documents/agents_brain/01_knowledge/
• Sub-folder Dokumen Proyek (symlink): ~/Documents/agents_brain/04_projects/robotik-pnp/ → ~/Documents/Project/robotik-pnp/docs/ (seluruh docs/ proyek ini tersedia di dalam vault).

(Catatan: Di root proyek ini tersedia symlink ./.brain/ yang menunjuk ke root vault. Agen diizinkan membaca/menulis langsung melalui ./.brain/, misal ./.brain/02_agent_memory/. Symlink ini di-gitignore dan tidak boleh di-commit).

11.2 Protokol Membaca Memori (Read Protocol)

Sebelum mengerjakan tugas yang melibatkan salah satu dari domain berikut:

1. Supabase SSR / Auth / RLS, atau pola Server Actions + validasi Zod.
2. Logika RBAC & domain inti (piket, absensi QR dinamis, kedisiplinan/SP, oprec).
3. Styling Tailwind CSS v4 & design system (@theme, token --color-*).

AI Agent WAJIB memeriksa catatan terdahulu di ~/Documents/agents_brain/02_agent_memory/ untuk melihat apakah ada keputusan teknis, gotchas, atau solusi bug serupa yang pernah dicatat sebelumnya. Catatan relevan yang sudah ada antara lain:

• robotik-pnp-security-audit-mrc-form
• robotik-pnp-qa-security-fixes-idor-ssrf-quota
• robotik-pnp-supabase-cloud-to-local-sync
• robotik-pnp-mrc-admin-panel-5-halaman
• robotik-pnp-mrc-rules-section-and-faq
• robotik-pnp-bugfix-mrc-stale-quota-isr

11.3 Protokol Menulis Memori (Write Protocol)

AI Agent WAJIB membuat catatan baru ketika:

1. Menemukan dan menyelesaikan subtle bug atau quirk khusus (misal: perilaku Supabase SSR cookie, kamera/QR mobile, autoplay audio policy).
2. Mengambil keputusan arsitektur baru (Architectural Decision Record / ADR).
3. Menyelesaikan optimasi performa komputasi atau bundler.

Setelah menulis catatan baru, daftarkan tautannya di Index.md vault (bagian 02_agent_memory dan daftar proyek Robotik-PNP).

Format Standar File Memori:

• Lokasi Simpan: ~/Documents/agents_brain/02_agent_memory/robotik-pnp-<kategori>-<topik-singkat>.md
• Struktur Markdown & YAML Frontmatter:

---
title: "Deskripsi Singkat Solusi / Keputusan"
project: "robotik-pnp"
date: YYYY-MM-DD
type: "bugfix" # Pilihan: bugfix | adr | gotcha | optimization
tags:
  - robotik-pnp
  - supabase-ssr # sesuaikan topik (misal: rls, server-actions, zod, piket, tailwind-v4, qr-absensi)
  - agent-memory
---

## 1. Konteks Masalah / Latar Belakang

Penjelasan ringkas tentang kendala yang dihadapi atau keputusan yang perlu dibuat.

## 2. Analisis Akar Masalah (Root Cause)

Mengapa masalah tersebut terjadi atau alasan pemilihan pendekatan tertentu.

## 3. Solusi Teknis & Implementasi

Rincian perubahan kode, file yang terpengaruh, atau snippet penting.

## 4. Pelajaran Penting (Gotchas untuk Sesi Mendatang)

Poin penting yang harus diingat agen di sesi berikutnya agar tidak mengulangi kesalahan yang sama.

## Lihat juga

- [[catatan-robotik-pnp-relevan-lainnya]]

Konvensi tambahan: akhiri setiap catatan dengan blok ## Lihat juga berisi tautan [[wikilink]] ke catatan robotik-pnp terkait, mengikuti gaya catatan yang sudah ada di 02_agent_memory/.

11.4 Definition of Done & Checklist Memori (WAJIB)

Aturan memori ini mengikat dan berlaku untuk setiap sesi di repo ini. Sumber otoritas tertinggi adalah ~/Documents/agents_brain/02_agent_memory/Preferences.md (dibaca saat sesi dimulai). Sebuah task belum dianggap selesai sebelum seluruh checklist berikut terpenuhi:

• Cek (READ): sebelum mulai, telusuri 02_agent_memory/ untuk catatan relevan dengan domain/tugas (lihat §11.2). Gunakan keputusan, gotchas, dan solusi terdahulu.
• Kerjakan task sesuai standar proyek.
• Klasifikasi (WRITE?): tentukan apakah hasil kerja memenuhi kriteria §11.3 (subtle bug / ADR / optimization).
• Jika ya — tulis catatan robotik-pnp-<kategori>-<topik>.md dengan format §11.3, lalu:
  • daftarkan [[wikilink]]-nya di Index.md (bagian 02_agent_memory dan daftar proyek Robotik-PNP);
  • perbarui baris *Last updated* di Index.md.
• Jika tidak — nyatakan eksplisit bahwa tidak ada catatan memori baru yang perlu dibuat, beserta alasannya.

Jangan menunda atau melewati langkah ini "karena tugas kecil" — disiplin ini yang menjaga context awareness lintas sesi.