Skip to main content

PRMKit.2 Technical Wiki

Version: 2.0.1 (Production) Last Updated: 2026-01-02 Status: Active Development

1. Introduction​

PRMKit.2 is a browser-first, cloud-native Project Resource Management system. It streamlines time tracking, project management, and resource allocation using SvelteKit for the frontend and Supabase for the backend.

Core Philosophy:

  • Security First: Logic is enforced at the database layer via Row-Level Security (RLS) and Stored Procedures (RPCs).
  • Single Source of Truth: The database (v1_baseline_...) is the authority on business rules.
  • Mobile Ready: Fully responsive UI component system.

2. Business Logic & Workflows​

2.1 User Management (profiles)​

  • Auto-Creation: Users are users created via Supabase Auth (Email/Google). A Trigger (handle_new_user) automatically creates a public.profiles record linked by auth_user_id.
    • Employee ID: Automatically generated (e.g., TEMP-xxxx) if not provided.
    • Email Sync: Changes to Auth email are synced to profiles via sync_auth_email_to_profile trigger.
  • Roles:
    • EMPLOYEE: Standard access.
    • MANAGER: Can manage assigned projects and approve timesheets.
    • ADMIN: Full system access.
  • Access: All authenticated users can read all profile basic info (for assignments/pickers).

2.2 Timesheet Workflow (timesheets)​

The timesheet lifecycle is a strict state machine managed by RPC functions to ensure data integrity.

  1. Draft: Employee creates entry.
    • Constraint: Unique per (employee, project, stage, date).
    • Edit: Employee can edit/delete freely.
  2. Submission (fn_log_submission):
    • Employee submits a timesheet.
    • System changes status: draft -> pending.
    • Approval Chain: Finds the first approver from profiles.approval_chain (or project manager) and creates an approvals record.
  3. Approval/Rejection:
    • Manager/Admin reviews.
    • Status updates to approved or rejected.
  4. Recall (fn_recall_timesheet):
    • Employee can recall a pending timesheet back to draft.
    • This deletes the pending approvals record.

2.3 Project & Resource Management​

  • Project Managers (project_managers): A many-to-many relationship defining who manages a project.
    • Function private.is_manager_of(project_id) checks permissions efficiently.
  • Assignments (project_assignments): Tracks which employees are working on which projects.
  • Budgets (project_budgets): Hour allocations per Stage.
  • Stages (stages): Reusable phase definitions (e.g., "Design", "Development") linked to projects.

2.4 Reporting​

  • Rollups: Heavy lifting is done in SQL.
    • fn_rollup_hours_by_stage(project_id, start, end): Returns aggregated hours (total, billable, non-billable) and unique employee counts for reporting dashboards.

3. Database Architecture​

The system uses a strict migration-based schema (supabase/migrations).

Core Tables​

TableRLS Policy Summary
profilesRead: All Auth Users. Update: Self & Admin.
projectsRead: All Auth Users. Write: Managers & Admins.
timesheetsRead: Owner, Project Manager, Admin. Write: Owner (Draft), PM/Admin key fields.
approvalsRead/Write: Project Managers & Admins.
stagesRead: All. Write: Admins only.
project_assignmentsRead: All. Write: Admins only.

Key Functions (RPCs)​

Located in 20251231002_v1_baseline_functions.sql:

  • fn_log_submission: Atomically submits timesheet and alerts approver.
  • fn_recall_timesheet: Reverts submission safely.
  • fn_import_timesheets: Bulk import from CSV (via Edge Function) with validation.
  • fn_export_employees: Admin-only data export.

4. Development Standards​

4.1 Coding Conventions​

  • UI & Documentation: English (International team standard).
  • Source Code Comments: Chinese (中文) (Internal dev team preference).
  • Styling:
    • Tailwind CSS first.
    • Bits UI for headless accessible components.

4.2 Database Migrations​

Format: YYYYMMDD###_v{Major}_{Snake_Case_Desc}.sql

  • Example: 20251231001_v1_baseline_schema.sql
  • Rules:
    • Never modify an applied migration.
    • Always create new file for changes.
    • Run supabase db push to apply.
    • Run supabase gen types typescript --linked to update types.

4.3 Deployment​

  • Frontend: Cloudflare Pages (Adapter: @sveltejs/adapter-cloudflare).
  • Backend: Supabase Cloud.
  • Environment: Secrets managed in Cloudflare Dashboard (Prod) and .env (Local).

5. Security Model (RLS Deep Dive)​

Security is not just a backend feature; it's the core of the application logic.

  • Employees: strict isolation. Can only modify their own draft timesheets.
  • Managers:
    • Can view ALL timesheets for projects they manage (project_managers table).
    • Can approve/reject timesheets for their projects.
    • Cannot modify system-wide settings or other projects.
  • Admins:
    • God-mode access (via get_my_role() = 'ADMIN' checks in policies).
    • Can manage stages, public_holidays, and csv_import_runs.