CLAUDE.md

1# CLAUDE.md
2 
3This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4 
5## Project Overview
6 
7sedekah.je is a directory of QR codes for mosques, suraus, and other religious institutions in Malaysia. It's a community-driven platform built with Next.js 14, TypeScript, PostgreSQL (Drizzle ORM), and Better Auth.
8 
9## Development Commands
10 
11```bash
12# Development
13bun dev                    # Start development server
14bun build                  # Production build
15bun start                  # Production server
16 
17# Code Quality
18bun run check              # Run Biome lint + format
19bun run lint               # Lint only
20bun run format             # Format code
21bun run type-check         # TypeScript checking
22 
23# Database
24bun run db:seed            # Seed database
25bun run db:truncate        # Clear database
26 
27# Utilities
28bun run clean              # Remove node_modules, .next, locks
29bun run import:walter-qrs  # Bulk QR import from scripts/data (see script header)
30bun run match:walter-institutions  # Read-only Walter vs existing similarity audit (see script header)
31bun run review:walter-medium       # GPT-4o-mini review of nameMatchesMedium (OPENAI_API_KEY; see script header)
32```
33 
34**Important**: This project uses Bun as the package manager and runtime. Always use `bun` instead of `npm` or `yarn`.
35 
36## Architecture
37 
38### App Router Structure (Next.js 13+)
39- `/app/(admin)/` - Admin dashboard with role-based access
40- `/app/(user)/` - User-facing features
41- `/app/api/` - API routes and server actions
42- `/app/[institution]/[slug]/` - Dynamic institution pages
43 
44### Key Directories
45- `/components/` - React components (uses shadcn/ui)
46- `/lib/` - Utilities, database queries, server actions
47- `/db/` - Database schema and migrations (Drizzle ORM)
48- `/hooks/` - Custom React hooks
49 
50### Database Schema
51Core entities:
52- **users** - Authentication and profiles
53- **institutions** - QR codes, locations, approval status
54- **auth sessions/accounts** - Better Auth tables
55 
56Workflow: Institutions go through Pending → Approved/Rejected states.
57 
58## Technology Stack
59 
60- **Framework**: Next.js 14 with App Router
61- **Database**: PostgreSQL with Drizzle ORM
62- **Auth**: Better Auth with Google OAuth
63- **Styling**: Tailwind CSS + shadcn/ui components
64- **Code Quality**: Biome (replaces ESLint + Prettier)
65- **State**: TanStack React Query + URL state (nuqs)
66- **Storage**: Cloudflare R2 for images
67- **Security**: Cloudflare Turnstile
68 
69## Development Guidelines
70 
71### Code Quality
72- Use Biome for all formatting and linting (tabs, 80 chars, configured in `biome.json`)
73- TypeScript strict mode - NO `any` types, proper inference
74- Run `bun run check` before committing
75- Follow Malaysian context for UI/UX (Bahasa Malaysia, payment systems)
76 
77### File Organization & Architecture
78**Feature-Based Structure** (avoid file type grouping):
79```
80app/(user)/feature/
81├── _lib/
82│   ├── queries.ts     # Server queries (cached with unstable_cache)
83│   ├── actions.ts     # Server actions (mutations)
84│   ├── validations.ts # Zod schemas
85│   └── types.ts       # TypeScript types
86├── _components/       # Private components
87└── page.tsx          # Route page
88```
89 
90### Key Principles
911. **Server Actions First** - Use server actions instead of API routes
922. **Avoid pg enums** - Use object constants for easier production management
933. **No useEffect for data fetching** - Fetch at server component, pass as props
944. **Server Components by Default** - Only use "use client" when needed
95 
96### Authentication (Better Auth)
97- Layout-based route protection: `/app/(user)/layout.tsx` and `/app/(admin)/layout.tsx`
98- Server-side: `const session = await auth.api.getSession({ headers: headers() })`
99- Client-side: `useAuth()` hook for user state
100- Roles: "user" (contributors) and "admin" (approval rights)
101 
102### Database Patterns (Drizzle ORM)
103- **Performance**: Wrap queries with `unstable_cache` for caching
104- **Batch Operations**: Use `inArray()` instead of Promise.all loops
105- **Counting**: Use Drizzle `count()` function, not `.length`
106- **Cache Invalidation**: Use `revalidateTag()` for targeted invalidation
107- **Schema**: Export types with `$inferSelect` and `$inferInsert`
108 
109### Form Handling Pattern
1101. Zod schema in `_lib/validations.ts`
1112. Server action in `_lib/actions.ts` with proper validation
1123. React Hook Form + useFormState for client component
1134. Always validate on server, handle authentication
1145. Use `revalidatePath()` after mutations
115 
116### Performance Optimizations
117- **UI Streaming**: Break complex pages into async components with `<Suspense>`
118- **Caching**: Use `unstable_cache` with appropriate TTL (300s for dynamic, 900s for stable)
119- **Server Components**: Fetch data at server level, minimize client-side requests
120 
121## Testing
122 
123No formal testing framework is currently set up. Consider this when making changes that require testing.
124 
125## Business Context (Malaysian Focus)
126 
127### Institution Types & Themes
128- `mosque` (masjid) - Blue theme color
129- `surau` - Green theme color  
130- `others` (lain-lain) - Violet theme color
131 
132### Payment Methods
133- `duitnow` - Malaysian instant payment system
134- `tng` - Touch 'n Go eWallet
135- `boost` - Boost eWallet
136 
137### Institution Workflow
138- `pending` - Awaiting admin approval (default for new submissions)
139- `approved` - Approved by admin and visible to public
140- `rejected` - Rejected by admin with reason
141 
142### Data Sources
143- **Static Data**: Historical institutions in `app/data/institutions.ts`
144- **Dynamic Data**: User-contributed institutions in PostgreSQL
145- **Combined Display**: Both sources shown together on maps and listings
146 
147## Special Features
148 
149- **QR Code Processing**: Automatic extraction and validation of payment QR codes
150- **Geolocation**: Institution mapping with Malaysian state-based filtering
151- **PWA**: Progressive Web App configuration
152- **Telegram Integration**: Logging for new user registrations and institution submissions
153- **Workflow Management**: Institution approval system with admin controls
154- **Malaysian States**: All 16 states and federal territories with flag support
155 
156## Common Tasks
157 
158### Adding New Institution Fields
1591. Update schema in `/db/schema/institutions.ts`
1602. Create migration with Drizzle
1613. Update form components in `/components/`
1624. Update validation schemas
163 
164### Adding New API Endpoints
1651. Create route in `/app/api/`
1662. Use server actions for mutations
1673. Add queries in `/lib/queries/`
1684. Update React Query hooks
169 
170### Database Operations
171- Connection configured through `DATABASE_URL`
172- Optional `DIRECT_URL` for connection pooling
173- Schema changes require migrations via Drizzle
174 
175Remember: This is a community project focused on Malaysian religious institutions. Maintain respect for the cultural context and ensure all QR codes are legitimate donation channels.