## 📝 Pre-Execution TODO Requirement **MANDATORY: Create TODO file before executing any complex task** ### **TODO Creation Process** 1. **Create TODO File**: Before starting any complex development task, create a detailed TODO file in the `TODO/` directory 2. **File Naming**: Use descriptive names like `TODO-(new-feature-name.md)` or `TODO-(bug-fix-description).md` 3. **Check Existing TODOs**: Review existing TODO files in `TODO/` directory to incorporate any pending tasks related to current prompt 4. **User Confirmation**: Present the TODO file to the user and wait for explicit confirmation before proceeding ### **TODO File Template** ```markdown # TODO: [Task Title] **Created by:** AI Assistant **Date:** [Current Date] **Purpose:** [Brief description of what will be accomplished] ## 📋 Task Breakdown ### Phase 1: [Phase Name] - [ ] [Specific task 1] - [ ] [Specific task 2] - [ ] [Specific task 3] ### Phase 2: [Phase Name] - [ ] [Specific task 1] - [ ] [Specific task 2] ## 🎯 Expected Outcomes - [ ] [Expected result 1] - [ ] [Expected result 2] ## ⚠️ Risks & Considerations - [Potential risk 1] - [Potential risk 2] ## 🔄 Dependencies - [Dependency 1] - [Dependency 2] ``` ### **User Confirmation Required** **Before executing any TODO:** 1. **Present TODO**: Show the complete TODO file content to the user 2. **Request Confirmation**: Ask "Do you approve this TODO and want me to proceed with execution?" 3. **Wait for Approval**: Only begin execution after user confirms with "yes", "approved", or similar confirmation 4. **Document Decision**: Note user's approval in the session ### **Automatic Task Progress Tracking** **MANDATORY: Update TODO file with completed task checkmarks** **During task execution:** 1. **Real-time Updates**: As each task or phase is completed, automatically update the TODO file in the previously created `TODO/TODO-(new-feature-name).md` to mark completed items with checkmarks 2. **Checkmark Format**: Replace `- [ ]` with `- [x]` for completed tasks 3. **Phase Completion**: Mark entire phases as complete when all tasks within that phase are finished 4. **Progress Visibility**: Keep the TODO file updated throughout the development session to show real-time progress 5. **CRITICAL: File Update Requirement**: After completing ANY task, you MUST immediately update the corresponding TODO file by changing `- [ ]` to `- [x]`. This is NOT optional - it is a mandatory requirement for every completed task. **Example Progress Updates:** ```markdown ### Phase 1: Database Setup - [x] Create Prisma models - [x] Generate database client - [x] Seed initial data ### Phase 2: API Development - [ ] Create CRUD endpoints - [ ] Add authentication - [ ] Test API routes ``` **Implementation Requirements:** - **Immediate Updates**: Update checkmarks IMMEDIATELY after completing each task - do not wait until the end of the phase - **File Synchronization**: Ensure the TODO file in `TODO/` directory reflects current progress at all times - **Completion Indicators**: Use clear visual indicators (checkmarks) for completed work - **Session Tracking**: Maintain progress visibility throughout the entire development session - **MANDATORY CHECK**: Before moving to the next task, verify that the previous task has been marked with `- [x]` in the TODO file - **NO EXCEPTIONS**: This requirement applies to ALL tasks - simple or complex, single or multi-step ### **When TODO is Required** Create TODO files for: - **New Features**: Multi-step feature development - **Major Refactoring**: Significant code restructuring - **Database Changes**: Schema modifications, migrations - **Complex Bug Fixes**: Issues requiring multiple steps - **Module Creation**: New application modules - **API Development**: Complete CRUD operations - **TODO Integration**: Include any pending tasks from existing TODO files that relate to current prompt execution ### **When TODO is NOT Required** Simple tasks that don't need TODO: - **Single file edits**: Minor fixes or updates - **Simple queries**: Information gathering - **Code reviews**: Analysis and suggestions - **Documentation**: README updates, minor docs **Example User Interaction:** ``` AI: I've created a TODO file for the new feature. Here's what I plan to do: [Shows complete TODO file content] Do you approve this TODO and want me to proceed with execution? User: Yes, please proceed. AI: ✅ TODO approved. Starting execution... [After completing first task] AI: ✅ Completed: Create Prisma models [Immediately updates TODO file: - [ ] becomes - [x]] [After completing second task] AI: ✅ Completed: Generate database client [Immediately updates TODO file: - [ ] becomes - [x]] [And so on for every task...] ``` --- ## 📋 Mandatory Requirements ### 1. README.md Updates **Update README.md only when deemed necessary after completing prompt execution.** - Document new features, modules, or components added - Update project structure if new directories/files are created - Add new API endpoints to the documentation - Update feature lists and capabilities - Include any breaking changes or important notes - Maintain the existing format and structure ### 2. UI Page Creation Requirements **ALWAYS add attribution to every file you create or modify.** Add this comment at the top of every new file: ```typescript /** * File: [filename] * Created by: Chandika Nurdiansyah (chandika@skatsa.com) * Date: [current date] * Purpose: [brief description of file purpose] * Part of: SDI Super App for PT Skatsa Data Integra */ ``` For modified files, add this comment above your changes: ```typescript /** * Modified by: Chandika Nurdiansyah (chandika@skatsa.com) * Date: [current date] * Changes: [brief description of changes] * Part of: SDI Super App for PT Skatsa Data Integra */ ``` --- ## 🏗️ Development Guidelines ### Code Standards - **TypeScript**: All code must be fully typed - **ESLint**: Follow existing linting rules (0 errors, 0 warnings) - **shadcn/ui**: Use consistent shadcn/ui components - **Prisma**: Use for all database operations - **Better Auth**: Follow authentication patterns - **Variable Naming**: All variables must use English language and camelCase format - **Label Naming**: All labels must be in English language ### Architecture Patterns - **Route Groups**: Use `(app)` for protected routes if not specifically asked - **API Structure**: Follow RESTful patterns in `/api/` directory - **Components**: Place reusable components in `/components/` - **Common Components**: Prioritize using existing components from `/components/Common/` before creating new ones - **Types**: Define TypeScript interfaces in `/types/` - **Hooks**: Custom hooks in `/hooks/` ### UI/UX Requirements - **Skeleton Loading**: Implement professional skeleton loading for all data tables - **shadcn/ui**: Use professional confirmation dialogs (not browser alerts) - **Responsive Design**: Mobile-first approach - **Error Handling**: Comprehensive error messages and recovery - **Loading States**: Smooth transitions and visual feedback - **Component Reuse**: Maximize use of existing Common components (AppTable, AppForm, etc.) before creating custom components - **Component Index Files**: ALWAYS include `index.ts` file in `/components/` and all subdirectories to export components for clean imports - **Mandatory Component Usage**: - ALL edit pages MUST use AppForm component - ALL table displays MUST use AppDataView component - ALL buttons MUST use ActionButton from `/components/ActionButton/index.ts` --- ## 📁 Project Structure Context ### **🏗️ Application Architecture** ``` /app/ ├── page.tsx # Homepage (public) ├── layout.tsx # Root layout ├── auth/ # Authentication (public) │ ├── signin/page.tsx # Sign in page │ └── signup/page.tsx # Sign up page ├── (system)/ # Route group (protected - system admin) │ ├── layout.tsx # AppLayout for system modules │ ├── dashboard/page.tsx # System dashboard │ └── user-management/ # User Management Module │ ├── users/page.tsx # Users list │ ├── user-groups/page.tsx # User groups │ ├── roles/page.tsx # Roles management │ └── authorization/page.tsx # Authorization matrix ├── (app)/ # Route group (protected - business apps) │ ├── layout.tsx # AppLayout for business applications │ └── finance-accounting/ # Finance & Accounting Module │ ├── page.tsx # Finance dashboard │ ├── chart-of-accounts/ │ │ ├── page.tsx # Chart of accounts list │ │ └── [id]/ │ │ └── edit.tsx # Edit account │ ├── journal-entries/ │ │ ├── page.tsx # Journal entries list │ │ └── new/ # New journal entry │ ├── ledger/ │ │ └── page.tsx # General ledger │ ├── transactions/ │ │ ├── page.tsx # Transactions list │ │ ├── new/ # New transaction │ │ └── [id]/ │ │ └── edit.tsx # Edit transaction │ └── reports/ │ └── page.tsx # Financial reports └── api/ # API routes ├── authorization/route.ts # Authorization API ├── users/route.ts # Users CRUD API ├── roles/route.ts # Roles CRUD API ├── user-groups/route.ts # User groups CRUD API ├── modules/route.ts # Modules API ├── applications/route.ts # Applications API └── finance-accounting/ # Finance APIs ├── chart-of-accounts/route.ts # Chart of accounts API ├── financial-transaction/route.ts # Transactions API ├── journal-entry/route.ts # Journal entries API ├── ledger/route.ts # Ledger API └── reports/route.ts # Financial reports API ``` ### **📋 Application Module Pattern** **Development Workflow for New Applications:** **Step 1: Database Schema Creation** 1. Create Prisma models in `prisma/models/[module-name]/` 2. Add models to main `prisma/schema.prisma` 3. Generate Prisma client: `pnpm db:generate` 4. Push schema to database: `pnpm db:push` 5. Create seed data in `prisma/seeds/[module-name]/index.ts` 6. Update main seed orchestrator `prisma/seed.ts` 7. Test seeding: `pnpm db:seed` **Step 2: UI Development** 1. Create application pages in `/app/(app)/application_name/` 2. Use `AppDataView` component for ALL data table displays 3. Use `AppForm` component for ALL forms (create, edit, update) 4. Use `ActionButton` from `/components/ActionButton/index.ts` for ALL buttons 5. Implement list, create, edit, and detail pages 6. Add proper routing and navigation 7. Ensure responsive design and loading states 8. Create custom components in `/components/` with proper `index.ts` exports 9. Follow component index file requirements for clean imports **Step 3: API Development** 1. Create API routes in `/app/api/application_name/` 2. Implement CRUD operations for each module 3. Add proper error handling and validation 4. Include authentication and authorization checks 5. Add TypeScript interfaces for request/response types 6. Test API endpoints thoroughly **Standard Pattern for New Applications:** ``` /app/(app)/application_name/ ├── page.tsx # Application dashboard/main page ├── module-1/ # First functional module │ ├── page.tsx # Module list view │ ├── new/ # Create new item │ └── [id]/ │ └── edit.tsx # Edit existing item ├── module-2/ # Second functional module │ ├── page.tsx # Module list view │ ├── new/ # Create new item │ └── [id]/ │ └── edit.tsx # Edit existing item └── module-n/ # Additional modules ├── page.tsx # Module list view ├── new/ # Create new item └── [id]/ └── edit.tsx # Edit existing item ``` **API Pattern for New Applications:** ``` /app/api/application_name/ ├── route.ts # Main application API ├── module-1/route.ts # Module 1 CRUD API ├── module-2/route.ts # Module 2 CRUD API └── module-n/route.ts # Module N CRUD API ``` ### **🗂️ Database Structure** ``` prisma/ ├── models/ # Model definitions by module │ ├── core/ # Core system models │ │ ├── user.prisma # User management │ │ ├── role.prisma # Role definitions │ │ ├── user-group.prisma # User groups │ │ └── module.prisma # System modules │ └── finance-accounting/ # Finance module models │ ├── chart-of-accounts.prisma # Chart of accounts │ ├── financial-transaction.prisma # Financial transactions │ ├── journal-entry.prisma # Journal entries │ ├── ledger.prisma # Ledger entries │ └── financial-report.prisma # Financial reports ├── seeds/ # Seed data by module │ ├── core/index.ts # Core system data │ └── finance-accounting/ # Finance module data │ ├── index.ts # Finance seeding │ └── sample-data.ts # Sample data ├── schema.prisma # Main consolidated schema └── seed.ts # Modular seed orchestrator ``` ### **🧩 Component Structure** ``` /components/ ├── index.ts # Main component exports ├── Common/ # Reusable common components │ ├── index.ts # Common components exports │ ├── AppLayout.tsx # Main application layout │ ├── AppTable.tsx # Data table component │ ├── AppForm.tsx # Form component │ ├── AppDataView.tsx # Data view component │ ├── LoadingSkeleton.tsx # Skeleton loading │ └── ConfirmDialog.tsx # Confirmation dialogs ├── ActionButton/ # Action button component │ └── index.ts # ActionButton export ├── Forms/ # Form components │ ├── index.ts # Forms exports │ └── [form-components].tsx ├── Charts/ # Chart components │ ├── index.ts # Charts exports │ └── [chart-components].tsx └── Layouts/ # Layout components ├── index.ts # Layouts exports └── [layout-components].tsx ``` **Component Index File Requirements:** **MANDATORY: Every component directory MUST include `index.ts` file** ```typescript // Example: /components/Common/index.ts export { default as AppLayout } from "./AppLayout"; export { default as AppTable } from "./AppTable"; export { default as AppForm } from "./AppForm"; export { default as AppDataView } from "./AppDataView"; export { default as LoadingSkeleton } from "./LoadingSkeleton"; export { default as ConfirmDialog } from "./ConfirmDialog"; // Example: /components/ActionButton/index.ts export { default as ActionButton } from "./index"; ``` **Usage Benefits:** - Clean imports: `import { AppTable, AppForm } from '@/components/Common'` - Clean button imports: `import ActionButton from '@/components/ActionButton'` - Centralized exports for better maintainability - Consistent import patterns across the application - Easy component discovery and usage ### **📚 Type Definitions** ``` /types/ ├── prisma.ts # Prisma type definitions ├── auth.ts # Authentication types ├── api.ts # API response types └── common.ts # Common utility types ``` ### **🎯 Module Access Patterns** - **Core System**: `/app/(system)` - System administration - User management, roles, authorization, app management - Requires admin-level permissions - **Business Applications**: `/app/(app)` - Business operations - Finance & Accounting, future business modules - Requires role-based permissions per module - **Public Access**: `/app/auth` - Authentication - Sign in, sign up pages - No authentication required --- ## 🔐 Security & Authorization ### Permission System - **Role-based Access Control**: Admin, Manager, User roles - **Module Permissions**: canView, canCreate, canUpdate, canDelete - **Advanced Permissions**: canApprove, canExport, canImport - **Custom Permissions**: JSON-based for specialized requirements ### Audit Trail Every table (except User Management) automatically includes: - `createdBy`, `createdAt`, `lastUpdateBy`, `lastUpdateAt` - `ownedBy` for group-based data ownership --- ## 🚀 Quality Assurance ### Before Completing Any Prompt 1. **Run linting**: `pnpm lint` (must be 0 errors, 0 warnings) 2. **Type checking**: `pnpm tsc --noEmit` (must be 0 errors) 3. **Build test**: `pnpm build` (must compile successfully) 4. **Test functionality**: Verify all features work as expected ### Testing Requirements - Authentication flows work end-to-end - CRUD operations function correctly - Permission matrix updates properly - Skeleton loading displays correctly - shadcn/ui components work properly - Real-time features function as expected ### Function Testing with MCP Server **MANDATORY: Use MCP Server for function testing** All function testing must be performed using MCP Server with the following configuration: ```json { "mcp": { "browser-mcp": { "type": "local", "command": ["npx", "@agentdeskai/browser-tools-server@latest"], "enabled": true } } } ``` **Testing Requirements:** - **Browser Testing**: Use MCP Server for all UI function testing - **End-to-End Testing**: Verify complete user workflows through browser automation - **Interactive Testing**: Test form submissions, button clicks, and navigation - **Data Validation**: Verify data persistence and retrieval through browser interface - **Error Handling**: Test error scenarios and user feedback mechanisms - **Responsive Testing**: Verify functionality across different screen sizes - **Performance Testing**: Monitor loading times and user interactions **MCP Server Usage:** 1. **Start MCP Server**: Ensure browser-mcp server is running before testing 2. **Automated Testing**: Use browser automation tools for comprehensive testing 3. **Manual Verification**: Perform manual checks through browser interface 4. **Screenshot Testing**: Capture screenshots for visual regression testing 5. **Console Monitoring**: Check browser console for errors and warnings 6. **Network Monitoring**: Verify API calls and responses through browser dev tools --- ## 📚 Documentation Updates Required ### README.md Sections to Update - **Features**: Add new features and capabilities - **Project Structure**: Document new directories/files - **API Endpoints**: Add new API routes - **Database Schema**: Document new tables/fields - **Quick Reference**: Update URLs and commands - **Recent Updates**: Add to the updates section ### Component Documentation - Create README files for new major components - Update existing component documentation - Include usage examples and props documentation --- ## 🎯 Current Project Context ### **🏛️ Core System Modules** **Core System** (Accessible via `/app/(system)` - System Administration) - **User Management**: Complete CRUD for users, groups, roles, authorization - **App Management**: Registry for 27 business applications - **Dashboard**: Main overview with statistics - **Authorization Matrix**: Role-based permission management - **System Configuration**: Core system settings and preferences ### **📊 Business Applications** **Finance & Accounting** (Accessible via `/app/(app)/finance-accounting`) - **Chart of Accounts**: Complete account hierarchy management - **Financial Transactions**: Transaction recording and management - **Journal Entries**: Double-entry bookkeeping system - **General Ledger**: Comprehensive ledger reporting - **Financial Reports**: Balance sheet, income statement, cash flow **Business Applications Registry** (27 total applications) - **Business**: 7 apps (Procurement, Asset, Human Capital, Finance, etc.) - **Productivity**: 5 apps (Archive, Project, Document, Meeting, Task) - **Analytics**: 2 apps (Budget Planning, Secondary Data) - **Other Categories**: 13 apps across various domains (Support, Finance, Operations, Media, Management, Research, Infrastructure, Security) ### **🔐 Access Control** **Default Credentials** - **Admin**: admin/admin123 (full system access) - **Manager**: manager/manager123 (limited business access) - **User**: user/user123 (basic application access) **Module Access Patterns** - **Core System**: Requires admin-level permissions - **Business Applications**: Role-based permissions per module - **Public Access**: Authentication pages only --- ## ⚡ Quick Commands Reference ```bash # Development pnpm dev # Start development server pnpm build # Build for production pnpm lint # Run ESLint npx tsc --noEmit # Type checking # Database pnpm db:push # Push schema changes pnpm db:seed # Seed initial data pnpm db:studio # Open Prisma Studio # Quality Assurance pnpm clean:win # Clean and reinstall (Windows) ``` --- ## 📝 Session Checklist Before completing any development session, ensure: - [ ] README.md has been updated with all changes - [ ] APPS.md has been updated with all changes - [ ] All created/modified files have proper attribution - [ ] Code passes all linting and type checking - [ ] Build completes successfully - [ ] All functionality works as expected - [ ] Documentation is accurate and complete - [ ] Security best practices are followed - [ ] UI/UX standards are maintained - [ ] **CRITICAL: TODO file has been updated with checkmarks for ALL completed tasks** - [ ] **CRITICAL: Every `- [ ]` for completed work has been changed to `- [x]`** --- ## 🌱 Database Schema & Seeding Guide ### **📁 Modular Database Structure** The database schema is organized into modular directories for better maintainability: ``` prisma/ ├── models/ │ ├── core/ # Core module models (system-wide) │ │ ├── user.prisma # User management │ │ ├── role.prisma # Role definitions │ │ ├── user-group.prisma # User groups │ │ └── module.prisma # System modules │ └── finance-accounting/ # Finance module models │ ├── chart-of-accounts.prisma # Chart of accounts │ ├── financial-transaction.prisma # Financial transactions │ ├── journal-entry.prisma # Journal entries │ ├── ledger.prisma # Ledger entries │ └── financial-report.prisma # Financial reports ├── seeds/ │ ├── core/ # Core module seed data │ │ └── index.ts # Core data seeding │ └── finance-accounting/ # Finance module seed data │ ├── index.ts # Finance data seeding │ └── sample-data.ts # Sample financial data ├── schema.prisma # Main consolidated schema └── seed.ts # Modular seed orchestrator ``` ### **🎯 Module Access Mapping** - **Core Module**: Accessible via `/app/(system)` - Contains system-wide data - Models: User, Role, UserGroup, Module, Application, Auth - Seed: Roles, user groups, admin user, core modules, applications - **Finance-Accounting Module**: Accessible via `/app/(app)/finance-accounting` - Contains financial data - Models: ChartOfAccounts, FinancialTransaction, JournalEntry, Ledger, FinancialReport - Seed: Chart of accounts hierarchy, sample transactions, reports ### **🏗️ Creating New Database Models** #### **1. Model File Creation** Create new `.prisma` files in appropriate module directory: ```prisma // Example: prisma/models/finance-accounting/new-model.prisma model NewModel { id String @id @default(cuid()) createdAt DateTime @default(now()) createdBy String updatedAt DateTime @updatedAt updatedBy String // Add your fields here // Standard audit fields (required for all models except User Management) @@map("new_models") } ``` #### **2. Schema Integration** Add model to main `prisma/schema.prisma`: ```prisma // ======================================== // FINANCE-ACCOUNTING MODULE MODELS // ======================================== model NewModel { // ... model definition from above } ``` #### **3. Client Generation** ```bash pnpm db:generate # Regenerate Prisma client with new models ``` #### **4. Database Migration** ```bash pnpm db:push # Push schema changes to database ``` ### **🌱 Module-Based Seeding Requirements** #### **Core Module Seeding** File: `prisma/seeds/core/index.ts` ```typescript export async function seedCoreData(prisma: PrismaClient) { // Create core system data const adminRole = await prisma.role.upsert({...}); const adminUser = await prisma.user.upsert({...}); return { adminRole, adminUser, // ... other core data }; } ``` #### **Finance Module Seeding** File: `prisma/seeds/finance-accounting/index.ts` ```typescript export async function seedFinanceAccountingData(prisma: PrismaClient, adminUser: any, adminGroup: any) { // Create finance-specific data const chartOfAccounts = await prisma.chartOfAccounts.upsert({...}); return { chartOfAccounts, // ... other finance data }; } ``` #### **Main Seed Orchestrator** File: `prisma/seed.ts` ```typescript import { seedCoreData } from "./seeds/core"; import { seedFinanceAccountingData } from "./seeds/finance-accounting"; async function main() { // Seed Core Module const { adminUser, adminGroup } = await seedCoreData(prisma); // Seed Finance Module (depends on core data) await seedFinanceAccountingData(prisma, adminUser, adminGroup); } ``` ### **📋 Mandatory Seeding Requirements** **IMPORTANT: Every time a new module is added, this seeding guide section MUST be updated** to include the new module's seeding requirements and workflow. **ALL new models and modules MUST be added to appropriate seed files** to ensure: #### **New Model Seeding** 1. **Create Seed Function**: Add seeding logic to appropriate module seed file 2. **Handle Dependencies**: Ensure dependent data is created first 3. **Data Consistency**: Use same data structure across environments 4. **Test Seeding**: Verify with `pnpm db:seed` #### **Module Dependencies** - **Core Module**: Independent (seeds first) - **Finance Module**: Depends on Core (needs adminUser, adminGroup) - **Future Modules**: Define dependencies clearly #### **Seeding Workflow** 1. **Create Model**: Define new Prisma model in module directory 2. **Update Schema**: Add to main schema.prisma 3. **Generate Client**: `pnpm db:generate` 4. **Add Seed Data**: Create seeding function in module seed file 5. **Update Main Seed**: Call new seed function in proper order 6. **Test**: `pnpm db:push && pnpm db:seed` 7. **Verify**: Check data with `pnpm db:studio` ### **🔧 Type Definitions** Update `/types/prisma.ts` for new models: ```typescript export interface NewModelWithRelations { id: string; // ... fields // Include related models if needed } ``` ### **✅ Verification Commands** ```bash # Complete database reset and reseed pnpm db:push --force-reset && pnpm db:seed # Generate Prisma client pnpm db:generate # View database structure pnpm db:studio # Test build with new models pnpm build ``` ### **📝 Best Practices** #### **Model Organization** - **Module Separation**: Keep models in appropriate module directories - **Clear Naming**: Use descriptive model and field names - **Consistent Fields**: Include standard audit fields - **Proper Relations**: Define relationships clearly #### **Seeding Best Practices** - **Idempotent Operations**: Use upsert for safe re-seeding - **Dependency Order**: Seed dependent data after prerequisites - **Error Handling**: Include proper error handling and logging - **Data Validation**: Ensure seeded data meets constraints #### **Type Safety** - **Interface Updates**: Update TypeScript types for new models - **Proper Typing**: Use specific types instead of 'any' - **Relation Types**: Include related model types in interfaces **Remember**: Any model not properly seeded will cause missing data and broken functionality after database reset. --- ## 🤝 Collaboration Notes ### Communication Style - Be concise and direct in responses - Focus on the specific task requested - Provide clear explanations for complex changes - Use proper code formatting and structure ### Problem Solving - Always check existing code patterns before implementing new solutions - Follow established conventions and best practices - Consider security implications for all changes - Test thoroughly before marking tasks complete