Instruction file imported from code-tieumomo/task-master (.github/instructions/system.instructions.md). Copyright stays with the author.

📘 Project Specification

Web-based Project Management System (Sheet-like)

📘 Project Specification

Web-based Project Management System (Sheet-like)

1. 📌 Project Context

This project aims to replace Google Sheets used for project management with a web-based system that provides:

• Sheet-like flexibility
• Structured, database-backed data
• Better UX for frequent editing
• Scalable management of many projects
• Public shareable links for clients (view-only)

The system is designed for:

• Internal project management
• Client transparency
• Long-term maintainability and extensibility

2. 🎯 Core Objectives

• Replace Google Sheets for managing projects and tasks
• Provide inline, fast, sheet-like editing experience
• Support multiple projects simultaneously
• Separate internal data from client-visible data
• Allow public read-only access via shareable links without authentication

3. 🧱 Technology Stack

Backend

• Laravel 12+
• PHP 8.3+
• MySQL or PostgreSQL
• Cookie-based authentication (session)

Frontend

• Vue 3 (Composition API)
• Inertia.js
• Vite
• Tailwind CSS
• Shadcn-Vue (UI components)

Auth

• Laravel Breeze (Vue + Inertia)
• Cookie-based session auth
• CSRF protected

Architecture

• Monorepo
• Server-driven SPA (Inertia)
• No REST API for internal UI
• Controllers return Inertia responses

4. 👤 User Roles & Permissions

This project do not require complex roles. Just login users.

5. 📁 Domain Model Overview

5.1 Users

users
- id
- name
- email
- password
- created_at
- updated_at

5.2 Projects

projects
- id
- name
- client_name
- description
- status (planning | in_progress | on_hold | completed)
- start_date
- end_date
- owner_id
- created_at
- updated_at
- deleted_at

Relations:

• Project belongsTo User (owner)
• Project hasMany Tasks
• Project hasMany ProjectMembers
• Project hasOne PublicLink

5.3 Project Members

project_members
- id
- project_id
- user_id

5.4 Tasks (Sheet Rows)

tasks
- id
- project_id
- title
- description
- phase
- priority (low | medium | high)
- status (todo | doing | review | done)
- assignee_id (nullable)
- start_date
- due_date
- progress (0–100)
- notes
- is_client_visible (boolean)
- sort_order
- created_at
- updated_at
- deleted_at

Indexes:

• project_id
• assignee_id
• status
• sort_order

5.5 Custom Columns (Extensible Sheet)

project_columns
- id
- project_id
- name
- type (text | number | date | select)
- options (json)
- is_client_visible
- sort_order

task_column_values
- id
- task_id
- project_column_id
- value (text)

5.6 Public Project Links

public_links
- id
- project_id
- token (uuid)
- password (nullable)
- expires_at (nullable)
- is_active

5.7 Activity Logs

activity_logs
- id
- user_id (nullable)
- project_id
- task_id (nullable)
- action
- changes (json)
- created_at

6. 🌐 Routing & Controllers (Inertia-first)

Authenticated Routes

Route::middleware('auth')->group(function () {
    Route::resource('projects', ProjectController::class);
    Route::get('projects/{project}/tasks', TaskController::class);
    Route::patch('tasks/{task}/inline', InlineTaskUpdateController::class);
    Route::post('tasks/reorder', TaskReorderController::class);
});

Public Access

Route::get('/p/{token}', PublicProjectController::class);

7. ⚡ Sheet-like Editing Behavior

Inline Editing

• Each cell is editable independently
• Update happens on blur / enter
• Autosave (no save button)
• Optimistic UI update on frontend

Inline Update Payload

{
  "field": "status",
  "value": "done"
}

Backend Responsibilities

• Authorize update
• Validate based on column type
• Update only one column
• Log activity

8. 🖥️ Frontend Structure (Vue + Inertia)

resources/js/
 ├─ Pages/
 │   └─ Projects/
 │       ├─ Index.vue
 │       └─ Show.vue
 │
 ├─ Components/
 │   └─ Sheet/
 │       ├─ SheetTable.vue
 │       ├─ SheetRow.vue
 │       └─ SheetCell.vue
 │
 ├─ Composables/
 │   ├─ useInlineEdit.ts
 │   └─ useReorder.ts

UX Guidelines

• Table-first UI
• Sticky header & columns
• Keyboard navigation (Tab / Enter)
• Debounced autosave
• Drag & drop row reorder

9. 📄 Inertia Props Contract

Example:

return Inertia::render('Projects/Show', [
  'project' => $project,
  'tasks' => $tasks,
  'columns' => $columns,
  'permissions' => [
      'canEdit' => Gate::allows('update', $project)
  ]
]);

10. 🌍 Public Client View

Characteristics

• No authentication
• View-only
• Minimal UI
• Mobile-friendly

Data Rules

• Only tasks where is_client_visible = true
• Only columns marked client-visible

11. 🔐 Security Considerations

• Cookie-based auth

• CSRF enabled

• Authorization via Policies

• Public link validation:

  • UUID token
  • Optional password
  • Optional expiration

• Soft deletes for core data

12. 🧪 Validation Rules

Examples:

• progress: integer (0–100)
• status: enum
• priority: enum
• Inline update must reject unknown fields

13. 🚀 Development Phases

Phase 1 (MVP)

• Authentication
• Project CRUD
• Task sheet (fixed columns)
• Inline editing
• Public shareable link

Phase 2

• Task sheet (full columns)
• Project members
• Activity logs
• Client visibility control

Phase 3

• Custom columns
• Export CSV / Excel
• Notifications

14. 🧠 Design Principles (Important for Copilot)

• Prefer clarity over abstraction
• No premature optimization
• Database-first design
• Inertia over REST for internal UI
• Sheet-like UX handled in frontend
• Public access isolated from auth system

15. 🤖 Instructions for AI / Copilot

When generating code:

• Follow this specification strictly
• Use Laravel best practices
• Prefer Policies over inline checks
• Keep controllers thin
• Keep Vue components small & reusable
• Assume future extensibility

This document is the single source of truth.