# TRAKYO — Claude Code Implementation Plan ## 1. Mission You are working on **TRAKYO**, a Laravel + React application for operational work management. Your job is to understand the current business model, respect the locked rules, and implement the system step by step with a clean architecture. This document is meant to help you: - understand the project - understand the business logic - know what is already decided - know what must be built - know what not to change - break implementation into clear development tasks --- ## 2. Tech Stack - **Backend:** Laravel - **Frontend:** React - **UI:** Tailwind CSS + shadcn/ui - **Target:** responsive web app, mobile-friendly - **Database:** relational DB (expected MySQL) - **Lang:** frensh + english --- ## 3. Core Product Idea TRAKYO is a system to manage: - users - teams - roles / permissions - business contacts - affaires - projects - tasks - task assignments - task work logs - affaire attachments - affaire expenses - future integrations and reporting The platform is designed to help teams: - organize work - execute project tasks - track who does what - group work under affaires - manage project visibility - manage expenses - prepare reporting and future business integrations --- ## 4. Locked Business Rules These rules are already decided and should be respected. ### 4.1 BusinessContact `BusinessContact` is a **tiers contact**. Current fields: - id - name - type - lat - lng A business contact can have many related contact persons. ### 4.2 BusinessContactPerson This is a separate entity linked to BusinessContact. Fields discussed: - firstname - lastname - civilité - poste - adresse - tel - email ### 4.3 User User has: - name - email - gsm - photo - internal_hourly_cost - billing_hourly_rate - status ### 4.4 Project Project is a separate module from Affaire. Rules: - Project belongs to one Affaire - One Affaire can have many Projects - Project has many Tasks - Project has **color** - Project has **tags** - Project stores **invoiced_amount** - Project includes: - name - state - visibility - is_internal ### 4.5 Task Rules: - Users start from **Project Tasks only** - Tasks belong to Project - Tasks may be assigned later - User starts and closes task - If allowed by permission, user may edit own task before submission ### 4.6 TaskWorkLog Rules: - TaskWorkLog belongs to Task - TaskWorkLog belongs to User - TaskWorkLog may optionally link to an existing Affaire - It tracks: - started_at - ended_at - duration_minutes - approval_status - cost_amount ### 4.7 Affaire Rules: - Affaire contains Projects - Affaire contains Attachments - Affaire contains Expenses - One Affaire can have many Expenses ### 4.8 Attachments Important rule: - **Attachments belong to Affaire, not Task** ### 4.9 Expenses Important rule: - **Expenses belong only to Affaire** - not directly to Task - not directly to Project ### 4.10 Permissions Important rule: - user can edit own task before submission only if permission allows it ### 4.11 Future integration Later: - BusinessContact may be imported or synchronized from **Dolibarr 19.0.2** Do not overbuild Dolibarr integration now, but keep structure compatible. --- ## 5. Current Simplified Domain Model ### Governance - User - Team - Role - Permission ### Business - BusinessContact - BusinessContactPerson - Affaire - Project - AffaireAttachment - AffaireExpense ### Execution - Task - TaskAssignment - TaskWorkLog --- ## 6. Relationships To Respect - Team has many Users - User may have Roles - Role may have Permissions - BusinessContact has many BusinessContactPersons - BusinessContact has many Affaires - Affaire has many Projects - Affaire has many AffaireAttachments - Affaire has many AffaireExpenses - Project has many Tasks - Project belongs to many Tags - Task has many TaskAssignments - Task has many TaskWorkLogs - TaskWorkLog may optionally link to one Affaire --- ## 7. Recommended Database Tables ### Governance - users - teams - roles - permissions - role_user - permission_role ### Business - business_contacts - business_contact_people - affaires - projects - tags - project_tag - affaire_attachments - affaire_expenses ### Execution - tasks - task_assignments - task_work_logs --- ## 8. Suggested Table Fields ## users - id - name - email - gsm - photo - internal_hourly_cost - billing_hourly_rate - status - team_id nullable - created_at - updated_at ## teams - id - name - code - leader_id nullable - created_at - updated_at ## roles - id - name - code - created_at - updated_at ## permissions - id - name - code - created_at - updated_at ## business_contacts - id - name - type - lat nullable - lng nullable - created_at - updated_at ## business_contact_people - id - business_contact_id - firstname - lastname - civilite nullable - poste nullable - adresse nullable - tel nullable - email nullable - created_at - updated_at ## affaires - id - business_contact_id - reference_number - title - status - created_at - updated_at ## projects - id - affaire_id - name - state - visibility - is_internal - color nullable - invoiced_amount nullable - created_at - updated_at ## tags - id - name - slug - color nullable - created_at - updated_at ## project_tag - id - project_id - tag_id ## tasks - id - project_id - title - planned_date nullable - billable_type - status - created_at - updated_at ## task_assignments - id - task_id - user_id - status - assigned_at nullable - created_at - updated_at ## task_work_logs - id - task_id - user_id - affaire_id nullable - started_at - ended_at nullable - duration_minutes nullable - approval_status - cost_amount - created_at - updated_at ## affaire_attachments - id - affaire_id - original_name - path - category nullable - created_at - updated_at ## affaire_expenses - id - affaire_id - amount - expense_date - approval_status - created_at - updated_at --- ## 9. Implementation Priorities Build in this order. ### Phase 1 — Foundation 1. Create migrations 2. Create models 3. Create relationships 4. Seed base roles and permissions 5. Seed some sample statuses if needed ### Phase 2 — Governance 1. User CRUD 2. Team CRUD 3. Role / permission management 4. User-role assignment 5. Policy or gate structure ### Phase 3 — Business Core 1. BusinessContact CRUD 2. BusinessContactPerson CRUD 3. Affaire CRUD 4. Project CRUD 5. Tag CRUD + ProjectTag management 6. AffaireAttachment upload/list/delete 7. AffaireExpense CRUD ### Phase 4 — Task Execution 1. Task CRUD under Project 2. Task assignment to users 3. Start task flow 4. Stop task flow 5. TaskWorkLog creation 6. Optional affaire linkage in TaskWorkLog 7. Self-task edit permission before submit 8. Basic approval status flow ### Phase 5 — UI / UX 1. Project pages 2. Task list and detail 3. Start/stop task UI 4. Affaire expense UI 5. Affaire attachment UI 6. Project tag and color UI ### Phase 6 — QA / Validation 1. Relationship checks 2. Permission checks 3. Expense-only-on-affaire checks 4. Attachment-only-on-affaire checks 5. Optional affaire linkage on work logs 6. Project color/tag checks --- ## 10. Concrete Development Tasks ## Task Group A — Schema - [x] Create `teams` migration - [x] Create `users` migration - [x] Create `roles` migration - [x] Create `permissions` migration - [x] Create `role_user` pivot migration - [x] Create `permission_role` pivot migration - [x] Create `business_contacts` migration - [x] Create `business_contact_people` migration - [x] Create `affaires` migration - [x] Create `projects` migration - [x] Create `tags` migration - [x] Create `project_tag` migration - [x] Create `tasks` migration - [x] Create `task_assignments` migration - [x] Create `task_work_logs` migration - [x] Create `affaire_attachments` migration - [x] Create `affaire_expenses` migration ## Task Group B — Models - [x] Create User model updates - [x] Create Team model - [x] Create Role model - [x] Create Permission model - [x] Create BusinessContact model - [x] Create BusinessContactPerson model - [x] Create Affaire model - [x] Create Project model - [x] Create Tag model - [x] Create Task model - [x] Create TaskAssignment model - [x] Create TaskWorkLog model - [x] Create AffaireAttachment model - [x] Create AffaireExpense model ## Task Group C — Relationships - [x] Add Team ↔ Users - [x] Add User ↔ Roles - [x] Add Role ↔ Permissions - [x] Add BusinessContact ↔ BusinessContactPersons - [x] Add BusinessContact ↔ Affaires - [x] Add Affaire ↔ Projects - [x] Add Affaire ↔ AffaireAttachments - [x] Add Affaire ↔ AffaireExpenses - [x] Add Project ↔ Tasks - [x] Add Project ↔ Tags - [x] Add Task ↔ TaskAssignments - [x] Add Task ↔ TaskWorkLogs - [x] Add TaskWorkLog ↔ optional Affaire ## Task Group D — Permissions / Policies - [x] Define permission names - [x] Create policy for task update - [x] Enforce: user can edit own task only if permission exists - [x] Enforce: own-task editing before submission only ## Task Group E — Business CRUD - [x] Build BusinessContact CRUD - [x] Build BusinessContactPerson CRUD - [x] Build Affaire CRUD - [x] Build Project CRUD - [x] Build Tag CRUD - [x] Build AffaireAttachment CRUD/upload - [x] Build AffaireExpense CRUD ## Task Group F — Task Execution - [x] Build Task CRUD - [x] Build TaskAssignment flow - [x] Build task start action - [x] Build task stop action - [x] Create TaskWorkLog on start/stop - [x] Allow optional affaire linkage in work log - [x] Add approval_status support ## Task Group G — Frontend - [x] Business contacts pages - [x] Affaires pages - [x] Projects pages - [x] Tasks pages - [x] Start/stop task interface - [x] Affaire attachments UI - [x] Affaire expenses UI - [x] Project color and tag UI ## Task Group H — Tests - [x] Test users/teams/roles/permissions - [x] Test business contact structure - [x] Test contact person structure - [x] Test affaire-project relationship - [x] Test project color/tag - [x] Test project invoiced_amount - [x] Test task start/stop flow - [x] Test optional affaire linkage in work log - [x] Test attachment belongs only to affaire - [x] Test expense belongs only to affaire - [x] Test own-task edit permission --- ## 11. Important Constraints Do **not** implement these incorrectly: - Do not attach files to Task in current version - Do not attach expenses to Task in current version - Do not attach expenses directly to Project in current version - Do not make Project optional if task is supposed to start from project tasks only - Do not move invoiced_amount to Affaire - Do not remove project color/tags - Do not ignore permission rule for own-task editing --- ## 12. Suggested Output Style for Claude Code When implementing, work in small safe steps: 1. create schema 2. create models and relations 3. create seeders 4. create backend CRUD 5. create policies 6. create frontend pages 7. add tests 8. summarize what was done When something is ambiguous, prefer to preserve the locked rules from this document instead of redesigning the model. --- ## 13. Acceptance Criteria This implementation plan is considered successful when: - schema matches locked business rules - Project has color, tags, invoiced_amount - Attachments are only on Affaire - Expenses are only on Affaire - TaskWorkLog can optionally link to Affaire - User can edit own task before submit only if permission allows - BusinessContact supports later Dolibarr sync - CRUD and task execution flows are operational - tests cover the critical relationships and permissions --- ## 14. Final Summary For Claude Code Build TRAKYO as a clean modular system with this structure: - BusinessContact → Affaire → Project → Task - Affaire → Attachments - Affaire → Expenses - Task → Assignments - Task → WorkLogs - WorkLog → optional Affaire - Project → color / tags / invoiced_amount - User → can edit own task before submit only if authorized Focus on correctness first, then UI polish, then future integration readiness.