Imported from iannn07/asdp-boilerplate (AGENTS.md). Install upstream with npx skills add iannn07/asdp-boilerplate. Copyright stays with the author.

ASDP Core Engine — Engineering Standards

Project Overview

ASDP Core Engine — internal dashboard/admin panel for managing ASDP port operations (vessel schedules, orders, billing, and payments) for ship owners, port operators, and administrators.

Technology Stack

Specification Standard

Every feature must have a written specification in DICE format before any code is written:

• D — Data Model: Every entity (table) the feature touches, with field types and constraints
• I — Interface Contract: Every API endpoint with auth, request/response shapes, and error codes
• C — Constraints & Business Rules: Numbered rules that govern behavior
• E — Evidence (Acceptance Criteria): Testable Given/When/Then statements

Spec files live in specs/[module-name].md. Use the DICE template in templates/DICE-spec-template.md.

The spec is the source of truth — not the code. When code and spec disagree, the spec wins and the code must be updated.

Coding Standards

• Write data type definitions BEFORE writing any logic
• All API endpoints MUST validate input before processing
• All API endpoints MUST check authentication and role before processing
• Use safe validation (safeParse()) — never throwing validation (parse()) for external data
• Error responses follow a consistent format: { error: string, code: string }
• All database tables MUST have: created_at, updated_at, created_by
• No direct database queries from the controller / route-handler layer
• Every UI component MUST handle 4 states: loading, error, empty, success
• Every code file should be traceable to a spec section
• Server Components by default; 'use client' only when state or interactivity is needed
• Use TailwindCSS className instead of sx or inline style for all components
• URL is the single source of truth for public parameters (page, pageSize, filters)
• Locale is managed via Zustand useUIStore — not cookies or URL
• Icons from @tabler/icons-react — never lucide-react
• cn() utility lives at src/lib/cn.ts (not src/lib/utils.ts)
• ThemeProvider uses attribute="data-theme" (not "class")
• Import order: external libs first, then @/ aliases (blank line between groups)
• Single quotes, no semicolons (enforced by Prettier)
• Server Actions use ActionResult<T> return type: { success: true; data: T } | { success: false; errors: Record<string, string> }
• Query key factories follow the pattern: featureKeys.all, featureKeys.list(), featureKeys.detail(id) in modules/[feature]/queries/
• Client components use useTranslation() hook for i18n; server-side uses getTranslations(locale)
• Locale message files live at src/locales/messages/{en,id}.json — namespaced by module

Roles

Roles are pending — the backend authentication system (Keycloak with Azure AD integration) has not been implemented yet. The auth adapter interface (src/lib/auth/) is a pluggable stub ready for integration.

Forbidden

These are hard bans — the AI agent must never do any of these:

• No raw SQL or direct database access from the frontend — all data goes through the backend API via src/lib/api/
• No skipping input validation on any endpoint
• No internal error details (stack traces, DB errors) returned to the client
• No secrets, API keys, or credentials committed to the repository
• No direct database access from the frontend — all data operations go through the backend API
• No deploying without passing all acceptance criteria from the spec
• No lucide-react imports — use @tabler/icons-react for all icons
• No editing files in src/components/ui/ — these are Shadcn-generated primitives
• No business logic in src/app/ page files — logic goes in src/modules/
• No direct Zustand mutations outside store files
• No cross-module imports between src/modules/ directories

Module Overview

Architecture Layers

Shared UI Library (src/components/) — domain-agnostic, follows strict Atomic Design:

Domain Modules (src/modules/) — self-contained feature units:

src/modules/[feature]/
├── actions/        # Server Actions ('use server')
├── components/     # Feature-specific UI components
├── data/           # Fallback / dummy data
├── hooks/          # Feature-specific custom hooks
├── queries/        # TanStack Query queryOptions + mutation fns
├── schemas/        # Valibot validation schemas
├── store/          # Zustand slice for this feature
└── types/          # Feature-specific TypeScript types

Infrastructure (src/lib/) — no UI, no domain logic:

Shared Utilities (src/utils/) — pure functions barrel-exported from index.ts:

Global Stores (src/store/):

Development Workflow

All features follow this stage pipeline. Each stage has a corresponding prompt in .cursor/prompts/:

Last Updated: 26 April 2026 Version: 1.0 Maintained By: Gunawan