# BMC-Shift — Comprehensive Spec (V1)

## 1. Overview

BMC-Shift is an internal platform for managing developer timesheets, project-level hours, costs, and attachments. It provides insight into how the business spends time, calculates true client cost, and helps prepare accurate reports and invoices. V1 focuses on **roles, clients, projects, project line-items, time entries, costs, and file management** — all with manual reporting and minimal automation.

---

## 2. Goals

* Provide clear **role-based permissions** for Admin, PM, Accountant, and Developer.
* Let Admins create **Clients**, **Projects**, and **Project Line-Items** (billable buckets).
* Assign developers to **projects** (and optionally specific line-items).
* Capture developer work logs with **date, description, hours, and role**.
* Support **static line-items** (e.g., Hosting @ $200/mo) and **dynamic cost items** (e.g., AI Credits $450/$700).
* Allow PM/Accountant to review, adjust, and approve time.
* Enable **manual report generation** and PDF storage.
* Manage files (uploads, receipts, demo videos, etc.) securely via DO Spaces.

---

## 3. Core Data Model

### **User**

* Fields: `_id, name, email, roles[], active`
* Roles: `admin`, `pm`, `accountant`, `developer`

### **Client**

* Fields: `_id, name, billingEmail, status`

### **Project**

* Fields: `_id, clientId, name, code, status, invoiceCycle ('monthly'|'mid_end')`

### **Project Line-Item**

* Purpose: billing-first buckets under a project (maps directly to invoice lines)
* Fields:

  ```json
  {
    "_id": "...",
    "projectId": "...",
    "name": "Mobile App Development",
    "code": "MOB-APP",
    "billing_code": "SERV-MOB",
    "type": "time" | "fixed_cost",
    "is_billable": true,
    "ratePerHour": 120,
    "default_adjustment_sec": 0,
    "recurring": {"enabled": false, "period": "monthly", "amountUSD": 0},
    "tags": ["frontend", "infra"],
    "active": true
  }
  ```

### **Membership**

* Links users to clients/projects (optionally line-items)
* Fields: `_id, userId, clientId, projectId?, projectItemId?, role, active`

### **Timesheet**

* Period-level doc grouping developer entries
* Fields: `_id, userId, month, year, status ('draft'|'submitted'|'approved'|'closed')`

### **TimeEntry**

* Tracks work logged by a developer for a specific client/project/line-item

  ```json
  {
    _id, sheetId, userId, clientId, projectId, projectItemId,
    date, notes, seconds,
    role: 'frontend'|'backend'|'infra'|'design',
    status: 'submitted'|'approved'|'rejected',
    attachments: [fileId]
  }
  ```

### **Adjustment**

* Adds or modifies time totals for a billing cycle

  ```json
  {
    _id, clientId, projectId?, projectItemId?,
    label, hoursSeconds, appliesAt: 'mid'|'end'|'both', month, year
  }
  ```

### **CostItem**

* Records variable or external costs linked to a project/line-item

  ```json
  {
    _id, clientId, projectId?, projectItemId?, label, costUSD, month, year, notes
  }
  ```

### **File**

* Stored in DigitalOcean Spaces

  ```json
  {
    _id, orgId, scope: 'client|project|projectItem|entry|report|invoice|misc',
    scopeId, uploaderId, originalName, s3Key, mime, size, sha256, tags, notes,
    createdAt, updatedAt
  }
  ```

---

## 4. Roles & Permissions

| Role           | Capabilities                                                            |
| -------------- | ----------------------------------------------------------------------- |
| **Admin**      | Full CRUD, user assignments, set rates, manage reports, close months    |
| **PM**         | Approve/reject time, manage projects and line-items, create adjustments |
| **Accountant** | Approve entries, manage costs, generate reports and invoices            |
| **Developer**  | Submit and edit own time entries, upload attachments                    |

---

## 5. Line-Item Types & Billing

### **Time-based line-items**

* Used for developer work; billable at `ratePerHour * totalHours`.

### **Fixed-cost line-items** (Static)

* Example: `Hosting` at $200/month → store as `type='fixed_cost'` with `recurring.enabled=true`.

### **Dynamic monthly costs**

* Example: AI Credits ($450/$350/$700) → captured as separate **CostItem** rows each month.
* Can optionally link a `CostItem.projectItemId` for grouping.

### **Rate Resolution (most-specific wins)**

1. `ratePerHour` on **Project Line-Item**
2. Rate override by `(client, project, role)`
3. Org default by role

### **Formula**

```
FinalHours(line-item) = Σ(approved entries) + Σ(adjustments)
LaborUSD(line-item) = FinalHours * resolvedRate
TotalUSD(project) = Σ(LaborUSD) + Σ(CostItems) + Σ(Recurring Fixed-Costs)
```

---

## 6. File Management

### Storage

* **Provider:** DigitalOcean Spaces (S3-compatible)
* **Key pattern:** `org/{orgId}/{scope}/{scopeId}/{yyyy}/{mm}/{base}-{timestamp}.{ext}`

### File API

| Endpoint                   | Description               |
| -------------------------- | ------------------------- |
| `POST /api/files/presign`  | Get signed upload URL     |
| `POST /api/files/complete` | Register metadata         |
| `GET /api/files`           | List by scope/scopeId/tag |
| `GET /api/files/:id/url`   | Signed download URL       |
| `PATCH /api/files/:id`     | Update tags/notes         |
| `DELETE /api/files/:id`    | Soft-delete + S3 delete   |

### Security

* Signed URLs (10-min TTL)
* Role-based read/write
* MIME allowlist: images, pdf, csv, video, excel, txt, zip

---

## 7. Time Tracking Flows

### Membership & Access Rules

* Users assigned at **project** level; optionally at **line-item** level.
* Developers can create entries **only for assigned projects/line-items**.

### Developer Flow

1. Select **Client → Project → Line-Item**.
2. Add **Date, Work Done, Role, and Hours**.
3. Attach files and submit.

### PM/Accountant Flow

1. Review submitted entries.
2. Approve or reject with comment.
3. Add adjustments at client/project/line-item scope.

### Admin Flow

1. Create clients, projects, and line-items.
2. Assign developers.
3. Manage approvals and end-of-month roll-ups.

---

## 8. Reporting (Manual in V1)

* Reports generated manually via `/api/reports/generate`.
* Include approved entries, adjustments, recurring fixed-costs, and cost items.
* Aggregates hours and costs per **project line-item** and role.
* Outputs HTML + PDF stored in Spaces.

### **Report Breakdown Example**

| Line-Item  | Role      | Hours | Rate | Cost | Subtotal   |
| ---------- | --------- | ----- | ---- | ---- | ---------- |
| Mobile Dev | Frontend  | 40    | $120 | –    | $4,800     |
| Infra      | Infra Eng | 20    | $100 | –    | $2,000     |
| Hosting    | Fixed     | –     | –    | $200 | $200       |
| AI Credits | Dynamic   | –     | –    | $450 | $450       |
| **Total**  |           |       |      |      | **$7,450** |

---

## 9. Implementation Order

1. **Setup & Roles**: Admin CRUD, role setup, client/project/line-item creation.
2. **Memberships**: Assign users to projects.
3. **Time Entry**: Developer form, list, edit, submit.
4. **Approvals & Adjustments**: PM/Accountant workflows.
5. **Costs & Reports**: Manual PDF generation.
6. **File Uploads**: Spaces integration.

---

## 10. Acceptance Criteria

* Admins can create clients, projects, and line-items.
* Developers restricted to assigned projects/line-items.
* Time entries and cost items roll up correctly.
* Reports generate accurate totals.
* Files upload successfully with signed URLs.
* System secure, auditable, and ready for automation later.

---

## 11. Future Enhancements

* AI auto-summaries of work.
* Vector search over notes/files.
* QuickBooks sync.
* Client portal.
* Automated reporting and notifications.
