Hugging Face's logo

Spaces:
triflix
/
eye
Sleeping

App Files Community
eye / Frontendplanner.md
triflix's picture
triflix
Upload 23 files
0a515cd verified
preview code
|
raw
history blame contribute delete
25.4 kB

Frontend Developer API Documentation

Architecture PM System - KillaDesign

Base URL: http://localhost:8000 (Development)
Framework: FastAPI
Database: PostgreSQL

Table of Contents

  1. Dashboard
  2. Projects
  3. Employees
  4. Timesheets
  5. Milestones
  6. Invoices
  7. Subcontractors
  8. Staff Allocation
  9. Data Models

Dashboard

Get Dashboard Statistics

Returns statistics for display on the home page.

Endpoint: GET /
Response Type: HTML Page
Description: Returns rendered HTML with dashboard statistics

Response Context:

{
  "projects_count": 0,
  "employees_count": 0,
  "timesheets_count": 0,
  "invoices_count": 0
}

Projects

1. List All Projects (HTML)

Endpoint: GET /projects
Response Type: HTML
Description: Returns rendered HTML page with projects list

2. List All Projects (API)

Endpoint: GET /api/projects
Response Type: JSON
Description: Returns array of all projects

Response Example:

[
  {
    "project_id": "PROJ001",
    "project_name": "Villa Design",
    "client_name": "ABC Corporation",
    "contract_value_aed": 500000.00,
    "planned_cost_aed": 400000.00,
    "project_start_date": "2024-01-01",
    "project_end_date": "2024-12-31",
    "project_type": "Residential",
    "project_status": "Active",
    "current_phase": "Design Development",
    "created_at": "2024-01-01T10:00:00Z",
    "updated_at": "2024-01-01T10:00:00Z"
  }
]

3. Create Project

Endpoint: POST /projects/create
Content-Type: application/x-www-form-urlencoded
Description: Creates a new project

Request Parameters:

Parameter Type Required Description
project_id string Yes Unique project identifier
project_name string Yes Name of the project
client_name string Yes Name of the client
contract_value_aed float Yes Contract value in AED
planned_cost_aed float Yes Planned cost in AED
project_start_date date Yes Start date (YYYY-MM-DD)
project_end_date date Yes End date (YYYY-MM-DD)
project_type string Yes Type of project
project_status string Yes Current status
current_phase string No Current project phase

Example Request (Form Data):

project_id=PROJ002
project_name=Modern Office Building
client_name=XYZ Ltd
contract_value_aed=1500000.00
planned_cost_aed=1200000.00
project_start_date=2024-02-01
project_end_date=2025-02-01
project_type=Commercial
project_status=Planning
current_phase=Initial Design

Response: Redirects to /projects (Status 303)

4. Delete Project

Endpoint: POST /projects/delete/{project_id}
Description: Deletes a project by ID

Path Parameters:

  • project_id: string - The project ID to delete

Response: Redirects to /projects (Status 303)

Employees

1. List All Employees (HTML)

Endpoint: GET /employees
Response Type: HTML
Description: Returns rendered HTML page with employees list

2. List All Employees (API)

Endpoint: GET /api/employees
Response Type: JSON
Description: Returns array of all employees

Response Example:

[
  {
    "employee_id": "EMP001",
    "employee_name": "John Doe",
    "department": "Architecture",
    "role": "Senior Architect",
    "hourly_rate_aed": 250.00,
    "employment_type": "Full-time",
    "start_date": "2023-01-15",
    "end_date": null,
    "cost_category": "Professional",
    "is_active": true,
    "email": "john.doe@example.com",
    "phone": "+971501234567",
    "created_at": "2023-01-15T09:00:00Z",
    "updated_at": "2023-01-15T09:00:00Z"
  }
]

3. Create Employee

Endpoint: POST /employees/create
Content-Type: application/x-www-form-urlencoded
Description: Creates a new employee

Request Parameters:

Parameter Type Required Description
employee_id string Yes Unique employee identifier
employee_name string Yes Employee's full name
department string Yes Department name
role string Yes Job role/title
hourly_rate_aed float Yes Hourly rate in AED
employment_type string Yes Full-time/Part-time/Contract
start_date date Yes Employment start date
cost_category string Yes Cost category classification
email string No Email address
phone string No Phone number

Example Request (Form Data):

employee_id=EMP002
employee_name=Jane Smith
department=Interior Design
role=Interior Designer
hourly_rate_aed=180.00
employment_type=Full-time
start_date=2023-06-01
cost_category=Professional
email=jane.smith@example.com
phone=+971507654321

Response: Redirects to /employees (Status 303)

4. Delete Employee

Endpoint: POST /employees/delete/{employee_id}
Description: Deletes an employee by ID

Path Parameters:

  • employee_id: string - The employee ID to delete

Response: Redirects to /employees (Status 303)

Timesheets

1. List All Timesheets (HTML)

Endpoint: GET /timesheets
Response Type: HTML
Description: Returns rendered HTML page with timesheets list, employees, and projects

2. List All Timesheets (API)

Endpoint: GET /api/timesheets
Response Type: JSON
Description: Returns array of timesheets (limited to 200 records)

Response Example:

[
  {
    "record_id": "TS001",
    "date": "2024-01-15",
    "employee_id": "EMP001",
    "project_id": "PROJ001",
    "hours_worked": 8.00,
    "billable_hours": 7.50,
    "work_category": "Design",
    "task_description": "Conceptual drawings and sketches",
    "is_approved": false,
    "created_at": "2024-01-15T18:00:00Z",
    "updated_at": "2024-01-15T18:00:00Z"
  }
]

3. Create Timesheet

Endpoint: POST /timesheets/create
Content-Type: application/x-www-form-urlencoded
Description: Creates a new timesheet entry

Request Parameters:

Parameter Type Required Description
record_id string Yes Unique record identifier
date date Yes Date of work (YYYY-MM-DD)
employee_id string Yes Employee ID (FK)
project_id string Yes Project ID (FK)
hours_worked float Yes Total hours worked
billable_hours float Yes Billable hours
work_category string Yes Category of work
task_description string No Description of tasks

Example Request (Form Data):

record_id=TS002
date=2024-01-16
employee_id=EMP001
project_id=PROJ001
hours_worked=8.00
billable_hours=8.00
work_category=Design Development
task_description=Detailed floor plans and elevations

Response: Redirects to /timesheets (Status 303)

4. Delete Timesheet

Endpoint: POST /timesheets/delete/{record_id}
Description: Deletes a timesheet entry by ID

Path Parameters:

  • record_id: string - The timesheet record ID to delete

Response: Redirects to /timesheets (Status 303)

Milestones

1. List All Milestones (HTML)

Endpoint: GET /milestones
Response Type: HTML
Description: Returns rendered HTML page with milestones list and projects

2. List All Milestones (API)

Endpoint: GET /api/milestones
Response Type: JSON
Description: Returns array of all milestones

Response Example:

[
  {
    "milestone_id": 1,
    "project_id": "PROJ001",
    "milestone_name": "Concept Design Approval",
    "milestone_order": 1,
    "planned_date": "2024-02-15",
    "actual_date": "2024-02-14",
    "status": "Completed",
    "completion_percentage": 100,
    "created_at": "2024-01-01T10:00:00Z",
    "updated_at": "2024-02-14T16:00:00Z"
  }
]

3. Create Milestone

Endpoint: POST /milestones/create
Content-Type: application/x-www-form-urlencoded
Description: Creates a new milestone

Request Parameters:

Parameter Type Required Description
project_id string Yes Project ID (FK)
milestone_name string Yes Name of milestone
milestone_order integer Yes Order/sequence number
planned_date date Yes Planned completion date
status string Yes Current status
completion_percentage integer No Completion % (0-100)
actual_date date No Actual completion date

Example Request (Form Data):

project_id=PROJ001
milestone_name=Design Development Complete
milestone_order=2
planned_date=2024-04-30
status=In Progress
completion_percentage=45

Response: Redirects to /milestones (Status 303)

4. Delete Milestone

Endpoint: POST /milestones/delete/{milestone_id}
Description: Deletes a milestone by ID

Path Parameters:

  • milestone_id: integer - The milestone ID to delete

Response: Redirects to /milestones (Status 303)

Invoices

1. List All Invoices (HTML)

Endpoint: GET /invoices
Response Type: HTML
Description: Returns rendered HTML page with invoices list and projects

2. List All Invoices (API)

Endpoint: GET /api/invoices
Response Type: JSON
Description: Returns array of all invoices

Response Example:

[
  {
    "invoice_id": "INV001",
    "project_id": "PROJ001",
    "invoice_date": "2024-02-01",
    "invoice_amount_aed": 50000.00,
    "due_date": "2024-03-01",
    "payment_date": "2024-02-28",
    "payment_status": "Paid",
    "days_outstanding": null,
    "milestone_reference": "Concept Design Approval",
    "paid_amount_aed": 50000.00,
    "created_at": "2024-02-01T10:00:00Z",
    "updated_at": "2024-02-28T14:30:00Z"
  }
]

3. Create Invoice

Endpoint: POST /invoices/create
Content-Type: application/x-www-form-urlencoded
Description: Creates a new invoice

Request Parameters:

Parameter Type Required Description
invoice_id string Yes Unique invoice identifier
project_id string Yes Project ID (FK)
invoice_date date Yes Invoice issue date
invoice_amount_aed float Yes Invoice amount in AED
due_date date Yes Payment due date
payment_status string Yes Payment status
payment_date date No Actual payment date
milestone_reference string No Related milestone

Example Request (Form Data):

invoice_id=INV002
project_id=PROJ001
invoice_date=2024-05-01
invoice_amount_aed=75000.00
due_date=2024-05-31
payment_status=Pending
milestone_reference=Design Development Complete

Response: Redirects to /invoices (Status 303)

4. Delete Invoice

Endpoint: POST /invoices/delete/{invoice_id}
Description: Deletes an invoice by ID

Path Parameters:

  • invoice_id: string - The invoice ID to delete

Response: Redirects to /invoices (Status 303)

Subcontractors

1. List All Subcontractors (HTML)

Endpoint: GET /subcontractors
Response Type: HTML
Description: Returns rendered HTML page with subcontractors list and projects

2. List All Subcontractors (API)

Endpoint: GET /api/subcontractors
Response Type: JSON
Description: Returns array of all subcontractors

Response Example:

[
  {
    "subcontractor_id": 1,
    "project_id": "PROJ001",
    "subcontractor_name": "Elite MEP Services",
    "service_type": "MEP Consultation",
    "contract_amount_aed": 150000.00,
    "amount_invoiced_aed": 50000.00,
    "payment_status": "Partially Paid",
    "work_category": "MEP Design",
    "contract_start_date": "2024-02-01",
    "contract_end_date": "2024-12-31",
    "contact_person": "Ahmed Ali",
    "contact_email": "ahmed@elitemep.com",
    "contact_phone": "+971504567890",
    "created_at": "2024-02-01T09:00:00Z",
    "updated_at": "2024-02-01T09:00:00Z"
  }
]

3. Create Subcontractor

Endpoint: POST /subcontractors/create
Content-Type: application/x-www-form-urlencoded
Description: Creates a new subcontractor

Request Parameters:

Parameter Type Required Description
project_id string Yes Project ID (FK)
subcontractor_name string Yes Subcontractor company name
service_type string Yes Type of service provided
contract_amount_aed float Yes Contract amount in AED
amount_invoiced_aed float No Amount invoiced (default: 0)
payment_status string Yes Payment status
work_category string Yes Work category
contact_person string No Contact person name
contact_email string No Contact email

Example Request (Form Data):

project_id=PROJ001
subcontractor_name=Structural Engineering Co
service_type=Structural Design
contract_amount_aed=80000.00
amount_invoiced_aed=0
payment_status=Not Started
work_category=Structural
contact_person=Mohammed Hassan
contact_email=mohammed@structural.com

Response: Redirects to /subcontractors (Status 303)

4. Delete Subcontractor

Endpoint: POST /subcontractors/delete/{subcontractor_id}
Description: Deletes a subcontractor by ID

Path Parameters:

  • subcontractor_id: integer - The subcontractor ID to delete

Response: Redirects to /subcontractors (Status 303)

Staff Allocation

1. List All Staff Allocations (HTML)

Endpoint: GET /staff-allocation
Response Type: HTML
Description: Returns rendered HTML page with staff allocations, projects, employees, and milestones

2. List All Staff Allocations (API)

Endpoint: GET /api/staff-allocation
Response Type: JSON
Description: Returns array of all staff allocations

Response Example:

[
  {
    "allocation_id": 1,
    "project_id": "PROJ001",
    "milestone_id": 1,
    "milestone_name": "Concept Design Approval",
    "employee_id": "EMP001",
    "employee_name": "John Doe",
    "role": "Senior Architect",
    "category": "Professional",
    "hours_allocated": 160.00,
    "hours_worked": 142.50,
    "hourly_rate_aed": 250.00,
    "skill_match_score": 95,
    "availability_status": "Available",
    "performance_rating": "Excellent",
    "start_date": "2024-01-01",
    "end_date": "2024-02-15",
    "notes": "Lead designer for concept phase",
    "created_at": "2024-01-01T10:00:00Z",
    "updated_at": "2024-02-15T16:00:00Z"
  }
]

3. Create Staff Allocation

Endpoint: POST /staff-allocation/create
Content-Type: application/x-www-form-urlencoded
Description: Creates a new staff allocation

Request Parameters:

Parameter Type Required Description
project_id string Yes Project ID (FK)
employee_id string Yes Employee ID (FK)
employee_name string Yes Employee's full name
role string Yes Role/position
hours_allocated float Yes Hours allocated
hours_worked float No Hours worked (default: 0)
hourly_rate_aed float Yes Hourly rate in AED
start_date date Yes Allocation start date
milestone_id integer No Milestone ID (FK)
milestone_name string No Milestone name
category string No Category classification
skill_match_score integer No Skill match score (0-100)
availability_status string No Availability status
performance_rating string No Performance rating
end_date date No Allocation end date
notes string No Additional notes

Example Request (Form Data):

project_id=PROJ001
employee_id=EMP001
employee_name=John Doe
role=Senior Architect
hours_allocated=160.00
hours_worked=0
hourly_rate_aed=250.00
start_date=2024-03-01
milestone_id=2
milestone_name=Design Development Complete
category=Professional
skill_match_score=95
availability_status=Available
performance_rating=Excellent
end_date=2024-04-30
notes=Lead architect for design development phase

Response: Redirects to /staff-allocation (Status 303)

4. Delete Staff Allocation

Endpoint: POST /staff-allocation/delete/{allocation_id}
Description: Deletes a staff allocation by ID

Path Parameters:

  • allocation_id: integer - The allocation ID to delete

Response: Redirects to /staff-allocation (Status 303)

Data Models

Project Model 

interface Project {
  project_id: string;          // Primary Key
  project_name: string;
  client_name: string;
  contract_value_aed: number;  // Decimal(15,2)
  planned_cost_aed: number;    // Decimal(15,2)
  project_start_date: string;  // Date (YYYY-MM-DD)
  project_end_date: string;    // Date (YYYY-MM-DD)
  project_type: string;
  project_status: string;
  current_phase?: string;
  created_at?: string;         // DateTime
  updated_at?: string;         // DateTime
}

Employee Model 

interface Employee {
  employee_id: string;         // Primary Key
  employee_name: string;
  department: string;
  role: string;
  hourly_rate_aed: number;     // Decimal(10,2)
  employment_type: string;
  start_date: string;          // Date
  end_date?: string;           // Date
  cost_category: string;
  is_active: boolean;
  email?: string;
  phone?: string;
  created_at?: string;         // DateTime
  updated_at?: string;         // DateTime
}

Timesheet Model 

interface Timesheet {
  record_id: string;           // Primary Key
  date: string;                // Date
  employee_id: string;         // Foreign Key
  project_id: string;          // Foreign Key
  hours_worked: number;        // Decimal(5,2)
  billable_hours: number;      // Decimal(5,2)
  work_category: string;
  task_description?: string;
  is_approved: boolean;
  approved_by?: string;
  approved_at?: string;        // DateTime
  created_at?: string;         // DateTime
  updated_at?: string;         // DateTime
}

Milestone Model 

interface Milestone {
  milestone_id: number;        // Primary Key (Auto)
  project_id: string;          // Foreign Key
  milestone_name: string;
  milestone_order: number;     // Integer
  planned_date: string;        // Date
  actual_date?: string;        // Date
  status: string;
  completion_percentage: number; // Integer (0-100)
  created_at?: string;         // DateTime
  updated_at?: string;         // DateTime
}

Invoice Model 

interface Invoice {
  invoice_id: string;          // Primary Key
  project_id: string;          // Foreign Key
  invoice_date: string;        // Date
  invoice_amount_aed: number;  // Decimal(15,2)
  due_date: string;            // Date
  payment_date?: string;       // Date
  payment_status: string;
  days_outstanding?: number;   // Integer
  milestone_reference?: string;
  paid_amount_aed: number;     // Decimal(15,2)
  created_at?: string;         // DateTime
  updated_at?: string;         // DateTime
}

Subcontractor Model 

interface Subcontractor {
  subcontractor_id: number;    // Primary Key (Auto)
  project_id: string;          // Foreign Key
  subcontractor_name: string;
  service_type: string;
  contract_amount_aed: number; // Decimal(15,2)
  amount_invoiced_aed: number; // Decimal(15,2)
  payment_status: string;
  work_category: string;
  contract_start_date?: string; // Date
  contract_end_date?: string;   // Date
  contact_person?: string;
  contact_email?: string;
  contact_phone?: string;
  created_at?: string;         // DateTime
  updated_at?: string;         // DateTime
}

Staff Allocation Model 

interface StaffAllocation {
  allocation_id: number;       // Primary Key (Auto)
  project_id: string;          // Foreign Key
  milestone_id?: number;       // Foreign Key
  milestone_name?: string;
  employee_id: string;         // Foreign Key
  employee_name: string;
  role: string;
  category?: string;
  hours_allocated: number;     // Decimal(10,2)
  hours_worked: number;        // Decimal(10,2)
  hourly_rate_aed: number;     // Decimal(10,2)
  skill_match_score?: number;  // Integer
  availability_status?: string;
  performance_rating?: string;
  start_date: string;          // Date
  end_date?: string;           // Date
  notes?: string;              // Text
  created_at?: string;         // DateTime
  updated_at?: string;         // DateTime
}

Common Response Formats

Success Response (JSON Endpoints) 

{
  "data": [ /* array of objects */ ]
}

Error Response 

{
  "detail": "Error message description"
}

HTTP Status Codes

  • 200 OK - Successful GET request
  • 303 See Other - Successful POST request (redirects)
  • 404 Not Found - Resource not found
  • 422 Unprocessable Entity - Validation error
  • 500 Internal Server Error - Server error

Frontend Implementation Notes

1. API Calls

  • All HTML endpoints return rendered pages
  • All /api/* endpoints return JSON data
  • Use /api/* endpoints for AJAX/Fetch requests
  • POST endpoints use form-urlencoded data and return redirects

2. Date Format

  • Input: YYYY-MM-DD (e.g., "2024-01-15")
  • Output: ISO format with timezone

3. Decimal Values

  • All monetary values are in AED
  • Use 2 decimal places for currency
  • Hours can use up to 2 decimal places

4. Foreign Key Relationships

  • Timesheets: Requires valid employee_id and project_id
  • Milestones: Requires valid project_id
  • Invoices: Requires valid project_id
  • Subcontractors: Requires valid project_id
  • Staff Allocation: Requires valid project_id, employee_id, optional milestone_id

5. Cascade Deletes

  • Deleting a Project will also delete:
    • All Milestones
    • All Subcontractors
    • All Staff Allocations
  • Deleting a Milestone will set milestone_id to NULL in Staff Allocations

6. Form Submission

All POST endpoints expect application/x-www-form-urlencoded data:

// Example using Fetch API
const formData = new FormData();
formData.append('project_id', 'PROJ001');
formData.append('project_name', 'New Project');
// ... add more fields

fetch('/projects/create', {
  method: 'POST',
  body: new URLSearchParams(formData)
});

7. AJAX Data Fetching

For dynamic data loading, use the /api/* endpoints:

// Example: Fetch all projects
fetch('/api/projects')
  .then(response => response.json())
  .then(data => {
    // data is an array of project objects
    console.log(data);
  });

Database Connection

  • Type: PostgreSQL
  • Hosted on: Render.com
  • Connection: Managed by SQLAlchemy ORM
  • Session Management: Automatic via dependency injection

CRUD Operations Summary

Resource List (JSON) Create Update Delete Get Single
Projects ✅ /api/projects ✅ ✅ (in CRUD) ✅ ✅ (in CRUD)
Employees ✅ /api/employees ✅ ✅ (in CRUD) ✅ ✅ (in CRUD)
Timesheets ✅ /api/timesheets ✅ ✅ (in CRUD) ✅ ✅ (in CRUD)
Milestones ✅ /api/milestones ✅ ✅ (in CRUD) ✅ ✅ (in CRUD)
Invoices ✅ /api/invoices ✅ ✅ (in CRUD) ✅ ✅ (in CRUD)
Subcontractors ✅ /api/subcontractors ✅ ✅ (in CRUD) ✅ ✅ (in CRUD)
Staff Allocation ✅ /api/staff-allocation ⚠️ (in CRUD only) ⚠️ (in CRUD only) ⚠️ (in CRUD only) ⚠️ (in CRUD only)

Note: Operations marked with ⚠️ are implemented in crud.py but not exposed as API endpoints in main.py. They can be added if needed.

Additional Features Available in CRUD Layer

The following functions are available in crud.py but not exposed as API endpoints:

Get Single Record

  • get_project(db, project_id: str)
  • get_employee(db, employee_id: str)
  • get_timesheet(db, record_id: str)
  • get_milestone(db, milestone_id: int)
  • get_invoice(db, invoice_id: str)
  • get_subcontractor(db, subcontractor_id: int)
  • get_staff_allocation(db, allocation_id: int)

Update Record

  • update_project(db, project_id: str, project: ProjectCreate)
  • update_employee(db, employee_id: str, employee: EmployeeCreate)
  • update_timesheet(db, record_id: str, timesheet: TimesheetCreate)
  • update_milestone(db, milestone_id: int, milestone: MilestoneCreate)
  • update_invoice(db, invoice_id: str, invoice: InvoiceCreate)
  • update_subcontractor(db, subcontractor_id: int, subcontractor: SubcontractorCreate)
  • update_staff_allocation(db, allocation_id: int, allocation: StaffAllocationCreate)

If you need these operations exposed as API endpoints, they can be added to main.py.

Contact & Support

For backend modifications or additional endpoints, contact the backend development team.

Document Version: 1.0
Last Updated: 2025-10-08
Generated for: Frontend Development Team