BarangaySystem/ai-docs/ai-guide.md

AI Assistant Navigation Guide

Reading Strategy

Start Here

1. repo-overview.md - Understand the project purpose, technologies, and high-level structure
2. architecture.md - Learn module interactions and data flows

Locating Code

3. Use file-map.json to find which module contains your target file
4. Use function-index.json to locate specific functions/classes by name

Reading Details

5. Read the corresponding module/*.md for component-level understanding
6. Read file/*.md for implementation details

When to Open Source Files

Only open original source files when:

• Implementation details are not documented
• Debugging requires exact line numbers
• Understanding edge cases not covered in documentation

Quick Reference

Task	Best Approach
Find login logic	Check LoginController in function-index.json, then read app/Http/Controllers/LoginController.php
Add new user role	Modify app/Enums/UserTypes.php, update permissions in UserPermissions
Create new product API	Add route in routes/web.php, create controller in app/Http/Controllers/Market/
File upload handling	Use FilesMainController@UploadFilefromRequest

Common Operations

Adding a New Page

1. Update file-map.json to add file mapping
2. Create Vue component in resources/js/Pages/
3. Add route in routes/web.php
4. Create controller if needed
5. Update viewmap config if server-side rendering required

Modifying User Permissions

1. Check UserActions enum in app/Enums/UserActions.php
2. Review UserPermissions::isActionPermitted() logic
3. Update role matrix as needed

Debugging API Endpoints

1. Find route in routes/web.php
2. Locate controller from function-index.json
3. Check middleware requirements in Kernel.php

Architecture Tips

• Vue Router: SPA routes handled via Vue's client-side routing
• Server Rendering: Use /p/{page}/s/ for server-rendered pages
• Permissions: Role checking happens via canDo() method on User model