professional_management/professional_management_platform_rest_plan.md

# Professional Management Platform
## Full REST-First System Design Plan

## 1. Product Vision

Build one shared backend platform that powers multiple profession-specific management applications.

Initial professions:

- Engineering
- Legal
- Healthcare

Future professions may include accounting, architecture, consulting, property management, veterinary practices, financial advisory, and other regulated or professional-service industries.

The core design principle is:

> **Share infrastructure, not domain meaning.**

Engineering projects, legal matters, and medical patients are fundamentally different concepts and should not be forced into the same universal business table.

---

## 2. Core Architecture Decision

The platform will use:

- REST
- JSON
- OpenAPI
- Versioned endpoints
- PostgreSQL
- Modular monolith backend
- Profession-specific frontends
- Profession-specific database tables
- Shared identity, security, billing, documents, audit, and infrastructure

Base API path:

```text
/api/v1
```

GraphQL is not part of v1.

---

## 3. High-Level Architecture

```text
                        FRONTENDS

       ┌──────────────────┼──────────────────┐
       │                  │                  │
 Engineering Web       Legal Web       Healthcare Web
       │                  │                  │
       └──────────────────┼──────────────────┘
                          │
                          ▼
                       REST API
                       /api/v1
                          │
              ┌───────────┼───────────┐
              │           │           │
            Core     Engineering     Legal
              │           │           │
              │       Healthcare      │
              │           │           │
              └───────────┼───────────┘
                          │
                      PostgreSQL
                          │
          ┌───────────────┼────────────────┐
          │               │                │
     Shared Tables   Profession Tables   Audit/Event Tables
```

Shared infrastructure:

```text
PostgreSQL
Redis
Object Storage
Queue / Workers
Audit
Notifications
Billing
Observability
```

---

## 4. System Architecture Strategy

Start with a modular monolith.

Do not start with microservices.

Initial deployment:

```text
Frontend Apps
     │
     ▼
Backend API
     │
     ├── PostgreSQL
     ├── Redis
     ├── Object Storage
     └── Worker Queue
```

Benefits:

- simpler transactions
- easier development
- easier deployment
- clearer domain boundaries
- lower operational burden
- easier refactoring
- future service extraction remains possible

---

## 5. Repository Structure

Recommended monorepo:

```text
professional-platform/
│
├── apps/
│   ├── engineering-web/
│   ├── legal-web/
│   ├── healthcare-web/
│   ├── platform-admin/
│   ├── api/
│   └── workers/
│
├── packages/
│   ├── ui/
│   ├── api-client/
│   ├── auth-client/
│   ├── validation/
│   ├── types/
│   ├── config/
│   └── testing/
│
├── database/
│   ├── migrations/
│   ├── seeds/
│   └── scripts/
│
├── infrastructure/
│   ├── docker/
│   ├── deployment/
│   └── monitoring/
│
└── docs/
    ├── architecture/
    ├── api/
    ├── security/
    └── domains/
```

---

## 6. Frontend Strategy

Every profession receives its own frontend application.

Avoid one giant frontend filled with profession checks.

### Engineering Frontend

Suggested navigation:

```text
Dashboard
Clients
Projects
Project Phases
Project Team
Sites
Designs
Design Reviews
Inspections
Specifications
Tasks
Documents
Timesheets
Billing
Reports
Administration
```

### Legal Frontend

Suggested navigation:

```text
Dashboard
Clients
Matters
Cases
Hearings
Courts
Deadlines
Documents
Conflict Checks
Time Tracking
Retainers
Billing
Reports
Administration
```

### Healthcare Frontend

Suggested navigation:

```text
Dashboard
Patients
Appointments
Practitioners
Encounters
Clinical Records
Diagnoses
Prescriptions
Insurance
Documents
Billing
Reports
Administration
```

### Platform Admin Frontend

Suggested functions:

```text
Organizations
Users
Profession Modules
Subscriptions
System Health
Audit
Support
Global Configuration
```

Platform administrators and organization administrators are separate concepts.

---

## 7. REST API Structure

Shared endpoints:

```text
/api/v1/auth
/api/v1/me
/api/v1/organizations
/api/v1/memberships
/api/v1/membership-invitations
/api/v1/roles
/api/v1/permissions
/api/v1/documents
/api/v1/invoices
/api/v1/payments
/api/v1/audit-events
```

Engineering:

```text
/api/v1/engineering/clients
/api/v1/engineering/projects
/api/v1/engineering/project-members
/api/v1/engineering/phases
/api/v1/engineering/sites
/api/v1/engineering/tasks
/api/v1/engineering/designs
/api/v1/engineering/inspections
/api/v1/engineering/specifications
/api/v1/engineering/time-entries
```

Legal:

```text
/api/v1/legal/clients
/api/v1/legal/matters
/api/v1/legal/cases
/api/v1/legal/hearings
/api/v1/legal/deadlines
/api/v1/legal/conflict-checks
/api/v1/legal/retainers
/api/v1/legal/time-entries
```

Healthcare:

```text
/api/v1/healthcare/patients
/api/v1/healthcare/practitioners
/api/v1/healthcare/appointments
/api/v1/healthcare/encounters
/api/v1/healthcare/clinical-records
/api/v1/healthcare/diagnoses
/api/v1/healthcare/prescriptions
/api/v1/healthcare/insurance
```

---

## 8. REST Conventions

All APIs use JSON.

Typical headers:

```http
Authorization: Bearer <access-token>
X-Organization-Id: org_123
Content-Type: application/json
```

Every tenant-scoped request requires organization context.

The server must verify:

1. user is authenticated
2. organization exists
3. membership exists
4. membership is active
5. required permission is present
6. resource belongs to the organization
7. resource policy permits access
8. profession-specific rules pass

---

## 9. Standard Response Format

Single resource:

```json
{
  "data": {
    "id": "project_123",
    "name": "Central Tower"
  }
}
```

Collection:

```json
{
  "data": [],
  "meta": {
    "pagination": {
      "nextCursor": null,
      "hasMore": false
    }
  }
}
```

Error:

```json
{
  "error": {
    "code": "PROJECT_NOT_FOUND",
    "message": "Project not found.",
    "details": {}
  }
}
```

Clients should rely on `error.code`, not human-readable messages.

---

## 10. HTTP Status Rules

```text
200 Success
201 Created
202 Accepted
204 No Content
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
409 Conflict
422 Validation Error
429 Too Many Requests
500 Internal Server Error
```

Cross-tenant resource access should return 404.

---

## 11. API Versioning

Current API:

```text
/api/v1
```

Breaking changes require:

```text
/api/v2
```

Additive fields generally do not require a new version.

---

## 12. Authentication

Initial authentication:

```text
Email
+
Password
+
Access Token
+
Refresh Token
```

Endpoints:

```http
POST /api/v1/auth/register
POST /api/v1/auth/login
POST /api/v1/auth/refresh
POST /api/v1/auth/logout
GET  /api/v1/me
```

Access tokens:

- short-lived
- signed
- identify user/session

Refresh tokens:

- rotated
- revocable
- stored hashed

Future:

- MFA
- passkeys
- SSO
- OAuth
- enterprise identity providers

---

## 13. Shared Core Backend

Recommended modules:

```text
core/
├── auth/
├── users/
├── organizations/
├── memberships/
├── roles/
├── permissions/
├── authorization/
├── documents/
├── billing/
├── notifications/
├── audit/
└── events/
```

Dependency rule:

```text
Profession module → Core
```

Never:

```text
Core → Profession module
```

---

## 14. Organizations

Organizations are tenants.

Examples:

```text
Atlas Structural Engineering
Smith & Associates Law
North Shore Medical Practice
```

Suggested fields:

```text
id
name
slug
status
country_code
timezone
currency_code
created_at
updated_at
```

---

## 15. Profession Enablement

Use:

```text
organization_professions
```

Suggested fields:

```text
organization_id
profession
enabled_at
configuration
```

Possible professions:

```text
engineering
legal
healthcare
```

An organization may eventually enable more than one profession module.

---

## 16. Users and Memberships

Users are global identities.

A user gains tenant access through membership.

```text
User
  │
  ▼
Membership
  │
  ▼
Organization
```

Suggested `users` fields:

```text
id
email
first_name
last_name
phone
avatar_url
status
created_at
updated_at
```

Suggested `memberships` fields:

```text
id
organization_id
user_id
status
joined_at
created_at
updated_at
```

---

## 17. Membership Invitations

Keep invitations separate from memberships.

Suggested table:

```text
membership_invitations
```

Fields:

```text
id
organization_id
email
invited_by_user_id
expires_at
accepted_at
revoked_at
created_at
```

Flow:

```text
Invitation
   ↓
Accepted
   ↓
User
   ↓
Membership
```

---

## 18. Authorization

Use:

```text
RBAC
+
Resource Policies
+
Professional Qualifications
```

Decision flow:

```text
Authenticated User
       ↓
Organization Membership
       ↓
Roles
       ↓
Permissions
       ↓
Permission Scope
       ↓
Resource Policy
       ↓
Professional Qualification Rule
       ↓
Domain State Rule
       ↓
ALLOW / DENY
```

Default decision:

```text
DENY
```

---

## 19. Roles and Permissions

Example roles:

```text
Owner
Administrator
Project Manager
Engineer
Lawyer
Paralegal
Doctor
Nurse
Billing Manager
Viewer
```

Example permissions:

```text
clients.read
clients.create
clients.update

documents.read
documents.upload

billing.read
invoices.issue
payments.record

engineering.projects.read
engineering.projects.manage
engineering.designs.approve

legal.matters.read
legal.matters.manage

healthcare.records.read
healthcare.records.write
```

---

## 20. Permission Scopes

Initial scopes:

```text
assigned
organization
```

Examples:

```text
Engineer:
engineering.projects.read = assigned

Principal Engineer:
engineering.projects.read = organization
```

Potential future scopes:

```text
owned
team
department
restricted
```

Do not implement until required.

---

## 21. Professional Credentials

Professional qualification is separate from RBAC.

Suggested table:

```text
professional_profiles
```

Fields:

```text
organization_id
user_id
profession
title
license_number
registration_number
jurisdiction
status
expiry_date
```

A user having a permission does not automatically mean they are professionally qualified to perform every regulated action.

---

## 22. Database Architecture

Use PostgreSQL.

Start with:

```text
One database
+
Shared schema
+
Profession-specific tables
```

Do not begin with database-per-profession or database-per-customer unless compliance or residency requirements force that choice.

---

## 23. Shared Tables

Recommended shared tables:

```text
organizations
organization_professions

users
user_credentials
sessions

memberships
membership_invitations

roles
permissions
role_permissions
membership_roles

professional_profiles

documents
document_versions

invoices
invoice_items
payments

notifications
notification_deliveries

audit_events
outbox_events
```

---

## 24. Multi-Tenancy Rule

Every tenant-owned row must contain:

```text
organization_id
```

Examples:

```text
engineering_projects.organization_id
legal_matters.organization_id
healthcare_patients.organization_id
```

Enforce tenant boundaries at:

- API layer
- authorization layer
- repository/query layer
- database constraints

---

## 25. Tenant-Safe Foreign Keys

Use composite tenant-aware foreign keys when possible.

Example:

```text
engineering_projects
organization_id
client_id
```

references:

```text
engineering_clients
organization_id
id
```

This prevents linking a resource from one organization to another organization's data.

---

# Engineering Domain

## 26. Engineering Tables

Initial tables:

```text
engineering_clients
engineering_projects
engineering_project_members
engineering_project_phases
engineering_sites
engineering_tasks
engineering_designs
engineering_design_versions
engineering_design_reviews
engineering_inspections
engineering_inspection_findings
engineering_specifications
engineering_change_requests
engineering_time_entries
```

---

## 27. Engineering Clients

Suggested fields:

```text
id
organization_id
client_type
display_name
legal_name
contact_name
email
phone
status
created_at
updated_at
```

REST:

```http
POST  /api/v1/engineering/clients
GET   /api/v1/engineering/clients
GET   /api/v1/engineering/clients/{clientId}
PATCH /api/v1/engineering/clients/{clientId}
POST  /api/v1/engineering/clients/{clientId}/archive
```

---

## 28. Engineering Projects

Suggested fields:

```text
id
organization_id
client_id
project_number
name
description
discipline
stage
status
project_manager_user_id
start_date
expected_completion_date
completed_date
budget_minor
currency_code
created_at
updated_at
version
```

REST:

```http
POST  /api/v1/engineering/projects
GET   /api/v1/engineering/projects
GET   /api/v1/engineering/projects/{projectId}
PATCH /api/v1/engineering/projects/{projectId}

POST /api/v1/engineering/projects/{projectId}/activate
POST /api/v1/engineering/projects/{projectId}/close
```

---

## 29. Engineering Project Members

Suggested fields:

```text
id
organization_id
project_id
user_id
project_role
joined_at
left_at
```

REST:

```http
GET    /api/v1/engineering/projects/{projectId}/members
POST   /api/v1/engineering/projects/{projectId}/members
PATCH  /api/v1/engineering/projects/{projectId}/members/{memberId}
DELETE /api/v1/engineering/projects/{projectId}/members/{memberId}
```

---

## 30. Engineering Project Phases

Suggested fields:

```text
id
organization_id
project_id
name
sequence
status
start_date
end_date
created_at
updated_at
```

Typical phases:

```text
Concept
Preliminary Design
Detailed Design
Construction
Inspection
Closeout
```

REST:

```http
GET  /api/v1/engineering/projects/{projectId}/phases
POST /api/v1/engineering/projects/{projectId}/phases
PATCH /api/v1/engineering/projects/{projectId}/phases/{phaseId}
POST /api/v1/engineering/projects/{projectId}/phases/{phaseId}/complete
```

---

## 31. Engineering Sites

Suggested fields:

```text
id
organization_id
project_id
name
address
latitude
longitude
created_at
updated_at
```

REST:

```http
POST  /api/v1/engineering/projects/{projectId}/sites
GET   /api/v1/engineering/projects/{projectId}/sites
GET   /api/v1/engineering/sites/{siteId}
PATCH /api/v1/engineering/sites/{siteId}
```

---

## 32. Engineering Tasks

Suggested fields:

```text
id
organization_id
project_id
title
description
status
priority
created_by_user_id
assigned_to_user_id
due_at
completed_at
created_at
updated_at
version
```

REST:

```http
POST  /api/v1/engineering/tasks
GET   /api/v1/engineering/tasks
GET   /api/v1/engineering/tasks/{taskId}
PATCH /api/v1/engineering/tasks/{taskId}

POST /api/v1/engineering/tasks/{taskId}/complete
POST /api/v1/engineering/tasks/{taskId}/reopen
POST /api/v1/engineering/tasks/{taskId}/cancel
```

---

## 33. Engineering Designs

Suggested fields:

```text
id
organization_id
project_id
design_number
title
description
discipline
status
prepared_by_user_id
approved_by_user_id
created_at
updated_at
version
```

Possible statuses:

```text
draft
under_review
changes_requested
approved
superseded
```

REST:

```http
POST  /api/v1/engineering/projects/{projectId}/designs
GET   /api/v1/engineering/projects/{projectId}/designs
GET   /api/v1/engineering/designs/{designId}
PATCH /api/v1/engineering/designs/{designId}

POST /api/v1/engineering/designs/{designId}/submit-review
POST /api/v1/engineering/designs/{designId}/request-changes
POST /api/v1/engineering/designs/{designId}/approve
```

Important approvals use explicit commands, not generic status PATCH operations.

---

## 34. Design Versions and Reviews

`engineering_design_versions`:

```text
id
design_id
version_number
document_id
created_by_user_id
created_at
```

`engineering_design_reviews`:

```text
id
organization_id
design_id
reviewer_user_id
status
comments
reviewed_at
```

Possible review statuses:

```text
pending
approved
changes_requested
rejected
```

---

## 35. Engineering Inspections

Suggested fields:

```text
id
organization_id
project_id
site_id
inspection_type
inspector_user_id
status
scheduled_at
performed_at
summary
created_at
updated_at
```

REST:

```http
POST  /api/v1/engineering/projects/{projectId}/inspections
GET   /api/v1/engineering/projects/{projectId}/inspections
GET   /api/v1/engineering/inspections/{inspectionId}
PATCH /api/v1/engineering/inspections/{inspectionId}

POST /api/v1/engineering/inspections/{inspectionId}/start
POST /api/v1/engineering/inspections/{inspectionId}/complete
```

---

## 36. Inspection Findings

Suggested fields:

```text
id
inspection_id
severity
description
status
resolved_at
```

Possible severities:

```text
observation
minor
major
critical
```

REST:

```http
POST  /api/v1/engineering/inspections/{inspectionId}/findings
PATCH /api/v1/engineering/inspection-findings/{findingId}
POST  /api/v1/engineering/inspection-findings/{findingId}/resolve
```

---

## 37. Engineering Specifications

Suggested fields:

```text
id
organization_id
project_id
specification_number
title
version
status
document_id
created_at
updated_at
```

---

## 38. Engineering Change Requests

Suggested fields:

```text
id
organization_id
project_id
request_number
title
description
status
requested_by_user_id
approved_by_user_id
estimated_cost_minor
created_at
updated_at
```

---

## 39. Engineering Time Entries

Suggested fields:

```text
id
organization_id
project_id
user_id
work_date
duration_minutes
description
billable
billing_rate_minor
currency_code
created_at
updated_at
```

REST:

```http
POST  /api/v1/engineering/time-entries
GET   /api/v1/engineering/time-entries
GET   /api/v1/engineering/time-entries/{id}
PATCH /api/v1/engineering/time-entries/{id}
```

Store duration as integer minutes.

---

# Legal Domain

## 40. Legal Tables

Initial tables:

```text
legal_clients
legal_matters
legal_matter_members
legal_cases
legal_case_parties
legal_courts
legal_hearings
legal_deadlines
legal_documents
legal_time_entries
legal_retainers
legal_conflict_checks
```

REST namespace:

```text
/api/v1/legal
```

Examples:

```http
GET  /api/v1/legal/clients
POST /api/v1/legal/matters
GET  /api/v1/legal/matters/{id}
POST /api/v1/legal/matters/{id}/close
GET  /api/v1/legal/cases
POST /api/v1/legal/hearings
POST /api/v1/legal/conflict-checks
```

---

## 41. Legal Matters

Suggested fields:

```text
id
organization_id
client_id
matter_number
title
practice_area
responsible_lawyer_user_id
status
opened_date
closed_date
created_at
updated_at
```

---

## 42. Legal Cases

Suggested fields:

```text
id
organization_id
matter_id
case_number
court_id
jurisdiction
case_type
status
filed_date
created_at
updated_at
```

---

## 43. Legal Hearings

Suggested fields:

```text
id
organization_id
case_id
hearing_type
scheduled_at
courtroom
judge
status
notes
```

---

## 44. Legal Conflict Checks

Suggested fields:

```text
id
organization_id
potential_client_name
related_parties
requested_by_user_id
reviewed_by_user_id
status
result
created_at
reviewed_at
```

---

# Healthcare Domain

## 45. Healthcare Tables

Initial tables:

```text
healthcare_patients
healthcare_practitioners
healthcare_appointments
healthcare_encounters
healthcare_clinical_records
healthcare_diagnoses
healthcare_prescriptions
healthcare_insurance
healthcare_allergies
healthcare_medications
```

REST namespace:

```text
/api/v1/healthcare
```

Examples:

```http
GET  /api/v1/healthcare/patients
POST /api/v1/healthcare/patients
POST /api/v1/healthcare/appointments
POST /api/v1/healthcare/encounters
GET  /api/v1/healthcare/clinical-records/{id}
POST /api/v1/healthcare/prescriptions
```

Healthcare must have stricter privacy, auditing, retention, and credential checks.

---

## 46. Healthcare Patients

Suggested fields:

```text
id
organization_id
patient_number
first_name
middle_name
last_name
date_of_birth
sex
phone
email
address
status
created_at
updated_at
```

---

## 47. Healthcare Practitioners

Suggested fields:

```text
id
organization_id
user_id
specialty
license_number
license_jurisdiction
credential_status
created_at
updated_at
```

---

## 48. Healthcare Appointments

Suggested fields:

```text
id
organization_id
patient_id
practitioner_id
appointment_type
starts_at
ends_at
status
reason
created_at
updated_at
```

---

## 49. Healthcare Encounters

Suggested fields:

```text
id
organization_id
patient_id
practitioner_id
appointment_id
encounter_type
started_at
ended_at
status
```

---

## 50. Clinical Records

Suggested fields:

```text
id
organization_id
patient_id
encounter_id
author_practitioner_id
record_type
content
created_at
updated_at
```

Sensitive clinical content may require application-level encryption.

---

# Shared Platform Services

## 51. Documents

Use shared object storage.

Database:

```text
documents
document_versions
```

Actual binary files:

```text
S3-compatible Object Storage
```

Suggested `documents` fields:

```text
id
organization_id
name
mime_type
size_bytes
created_by_user_id
created_at
updated_at
```

Suggested `document_versions` fields:

```text
id
document_id
version_number
storage_key
checksum
size_bytes
uploaded_by_user_id
created_at
```

---

## 52. Document Upload Flow

```text
Frontend
   ↓
Request upload URL
   ↓
Backend authorizes
   ↓
Signed upload URL
   ↓
Frontend uploads to object storage
   ↓
Backend finalizes document
   ↓
Virus/security scan
   ↓
Document becomes available
```

REST:

```http
POST /api/v1/documents/upload-url
POST /api/v1/documents/{documentId}/complete-upload
GET  /api/v1/documents/{documentId}
GET  /api/v1/documents/{documentId}/download-url
POST /api/v1/documents/{documentId}/versions
```

---

## 53. Profession-Specific Document Links

Use explicit tables where possible.

Engineering:

```text
engineering_project_documents
engineering_design_documents
engineering_inspection_documents
```

Legal:

```text
legal_matter_documents
legal_case_documents
```

Healthcare:

```text
healthcare_patient_documents
healthcare_encounter_documents
```

This gives stronger foreign-key integrity than generic polymorphic document links.

---

## 54. Billing

Shared financial core:

```text
invoices
invoice_items
payments
```

Profession-specific modules may extend billing workflows.

Engineering examples:

```text
project billing
hourly billing
milestone billing
```

Legal examples:

```text
matter billing
time billing
retainers
trust accounting
```

Healthcare examples:

```text
insurance
claims
patient billing
```

REST:

```http
POST  /api/v1/invoices
GET   /api/v1/invoices
GET   /api/v1/invoices/{invoiceId}
PATCH /api/v1/invoices/{invoiceId}

POST /api/v1/invoices/{invoiceId}/issue
POST /api/v1/invoices/{invoiceId}/void
POST /api/v1/invoices/{invoiceId}/payments
POST /api/v1/payments/{paymentId}/refund
```

---

## 55. Money Representation

Use integer minor units:

```json
{
  "amountMinor": 12550,
  "currency": "USD"
}
```

Meaning:

```text
$125.50
```

Never use floating point for money.

---

## 56. Audit Logging

Table:

```text
audit_events
```

Suggested fields:

```text
id
organization_id
actor_user_id
action
resource_type
resource_id
request_id
ip_address
user_agent
metadata
occurred_at
```

Examples:

```text
engineering.project.created
engineering.design.approved
legal.matter.created
legal.document.viewed
healthcare.record.viewed
invoice.issued
membership.role_changed
```

Audit logs are append-only.

REST:

```http
GET /api/v1/audit-events
```

No public create/update/delete endpoints.

---

## 57. Domain Events and Transactional Outbox

Profession modules produce internal domain events.

Examples:

```text
engineering.project.created
engineering.inspection.completed
legal.hearing.scheduled
healthcare.appointment.created
invoice.issued
```

Consumers:

```text
notifications
webhooks
analytics
search
integrations
background workflows
```

Use:

```text
outbox_events
```

Transaction pattern:

```text
BEGIN

business update
audit event
outbox event

COMMIT
```

Worker processes outbox events after commit.

---

## 58. Background Jobs

Workers handle:

```text
Email
SMS
Notifications
Report generation
PDF generation
File scanning
Document processing
Imports
Exports
Webhook delivery
Search indexing
Large data operations
```

Architecture:

```text
API
 ↓
Queue
 ↓
Worker
```

---

## 59. Redis

Use Redis for:

```text
job queue
rate limiting
short-lived caching
distributed locks
optional session support
```

PostgreSQL remains the authoritative source of truth.

---

## 60. Pagination

Use cursor pagination.

Example:

```http
GET /api/v1/engineering/projects?limit=25
```

Response:

```json
{
  "data": [],
  "meta": {
    "pagination": {
      "nextCursor": "...",
      "hasMore": true
    }
  }
}
```

Maximum page size:

```text
100
```

---

## 61. Filtering

Use explicit resource-specific filters.

Examples:

```http
GET /api/v1/engineering/projects?status=active&discipline=structural
GET /api/v1/engineering/tasks?status=todo&assignedToUserId=user_123
```

Do not build a generic query DSL in v1.

---

## 62. Sorting

Examples:

```http
GET /api/v1/engineering/projects?sort=createdAt
GET /api/v1/engineering/projects?sort=-createdAt
```

Only explicitly supported fields may be sorted.

---

## 63. Search

Start with PostgreSQL search.

Engineering search may cover:

```text
project number
project name
client name
```

Legal:

```text
matter number
client
case number
```

Healthcare:

```text
patient number
patient identity
```

Healthcare search requires tighter privacy controls.

Do not introduce Elasticsearch/OpenSearch until PostgreSQL is genuinely insufficient.

---

## 64. Optimistic Concurrency

Important mutable resources should use a version field.

Example:

```json
{
  "id": "project_123",
  "version": 6
}
```

Update:

```json
{
  "version": 6,
  "name": "Central Tower Phase II"
}
```

If the current database version differs:

```text
409 CONCURRENT_MODIFICATION
```

---

## 65. Domain-Oriented REST

Important state transitions use explicit command endpoints.

Good:

```http
POST /engineering/projects/{id}/close
POST /engineering/designs/{id}/approve
POST /engineering/tasks/{id}/complete
POST /engineering/inspections/{id}/complete
POST /invoices/{id}/issue
```

Avoid:

```http
PATCH /resource/{id}
{
  "status": "approved"
}
```

when the change has significant rules or side effects.

---

## 66. Transaction Boundaries

Create project:

```text
BEGIN

create project
assign project manager
write audit event
write outbox event

COMMIT
```

Approve design:

```text
BEGIN

validate permission
validate project access
validate credentials
validate design state
create review result
mark approved
write audit event
write outbox event

COMMIT
```

---

## 67. Request Context

Every authenticated request should resolve:

```text
RequestContext
{
    requestId
    userId
    sessionId
    organizationId
    membershipId
    permissions
}
```

Profession modules consume this context.

---

## 68. Request IDs

Every request has:

```http
X-Request-Id
```

If missing, the server generates one.

Use it in:

- logs
- audit context
- error diagnostics
- asynchronous correlation

---

## 69. OpenAPI

Maintain:

```text
openapi.yaml
```

OpenAPI should define:

- routes
- request DTOs
- response DTOs
- authentication
- error schemas
- pagination
- filters
- examples

Generate frontend API clients when practical.

---

## 70. DTO Rule

Database models are not public API contracts.

Use:

```text
Request DTO
Response DTO
```

A database migration should not accidentally change the public API.

---

## 71. Backend Module Structure

Recommended:

```text
src/
├── core/
│   ├── auth/
│   ├── organizations/
│   ├── memberships/
│   ├── authorization/
│   ├── documents/
│   ├── billing/
│   ├── audit/
│   └── events/
│
├── engineering/
│   ├── clients/
│   ├── projects/
│   ├── project-members/
│   ├── phases/
│   ├── sites/
│   ├── tasks/
│   ├── designs/
│   ├── inspections/
│   └── specifications/
│
├── legal/
│   ├── clients/
│   ├── matters/
│   ├── cases/
│   ├── hearings/
│   ├── conflicts/
│   └── retainers/
│
└── healthcare/
    ├── patients/
    ├── practitioners/
    ├── appointments/
    ├── encounters/
    ├── records/
    └── prescriptions/
```

---

## 72. Internal Module Structure

Example:

```text
projects/
├── domain/
│   ├── project.entity.ts
│   ├── project-status.ts
│   └── project.errors.ts
│
├── application/
│   ├── commands/
│   │   ├── create-project.ts
│   │   ├── update-project.ts
│   │   └── close-project.ts
│   │
│   └── queries/
│       ├── get-project.ts
│       └── list-projects.ts
│
├── infrastructure/
│   └── project.repository.ts
│
└── api/
    ├── project.controller.ts
    ├── project.request.ts
    └── project.response.ts
```

---

## 73. Controllers

Controllers should handle:

```text
HTTP
authentication context
input DTO parsing
application command/query invocation
response mapping
```

Controllers should not contain:

```text
business rules
raw SQL
role logic
transaction orchestration
email sending
audit implementation
```

---

## 74. Commands and Queries

Mutations use commands.

Examples:

```text
CreateEngineeringProjectCommand
ApproveEngineeringDesignCommand
CloseLegalMatterCommand
CompleteHealthcareEncounterCommand
```

Reads use queries.

Examples:

```text
GetEngineeringProjectQuery
ListLegalMattersQuery
GetHealthcarePatientQuery
```

---

## 75. Repositories

Use domain-specific repositories.

Examples:

```text
EngineeringProjectRepository
LegalMatterRepository
HealthcarePatientRepository
```

Avoid one massive generic repository abstraction that eventually needs dozens of flags.

---

## 76. Security Baseline

Minimum controls:

```text
TLS everywhere
strong password hashing
secure refresh token storage
rate limiting
RBAC
tenant isolation
input validation
SQL injection protection
signed object-storage URLs
audit trails
secret management
encryption at rest
dependency scanning
security headers
session revocation
```

---

## 77. Data Classification

Suggested classes:

### Public

```text
marketing configuration
```

### Internal

```text
organization settings
tasks
```

### Confidential

```text
engineering documents
legal matters
billing
```

### Highly Sensitive

```text
clinical records
professional credentials
authentication secrets
```

---

## 78. Healthcare Security

Before healthcare production use, define:

```text
privacy model
clinical access model
audit policy
retention policy
credential model
jurisdiction requirements
encryption strategy
consent requirements
data residency requirements
```

Healthcare should be treated as a stricter security tier.

---

## 79. Observability

Use:

```text
structured logs
metrics
distributed tracing
request IDs
```

Recommended:

```text
OpenTelemetry
```

Track:

```text
API latency
error rate
database latency
database connections
queue depth
worker failures
authentication failures
authorization denials
external service failures
```

---

## 80. Logging

Useful fields:

```text
request_id
route
method
status
duration
user_id when appropriate
organization_id when appropriate
```

Never log:

```text
passwords
tokens
clinical record text
full sensitive documents
payment secrets
```

---

## 81. Testing Strategy

### Unit Tests

Test:

```text
domain rules
authorization policies
calculations
state transitions
```

### Integration Tests

Test:

```text
repositories
PostgreSQL constraints
transactions
```

### API Tests

Test:

```text
routes
validation
authentication
authorization
error responses
```

### End-to-End Tests

Test complete professional workflows.

---

## 82. Tenant Security Tests

For every major resource, attempt:

```text
Organization A resource
using Organization B context
```

Test:

```text
read
update
delete/action
list filtering
search
documents
```

Expected result:

```text
404 / denied
```

---

## 83. Engineering MVP

Engineering is the first vertical.

Initial features:

```text
Authentication
Organization management
Users / memberships / roles
Engineering clients
Projects
Project members
Project phases
Tasks
Sites
Documents
Basic design records
Inspections
Time entries
Basic billing
Audit history
```

Do not initially build:

```text
advanced CAD integration
BIM integration
full document markup
advanced resource planning
procurement
complex accounting
AI design analysis
IoT integrations
```

---

## 84. Engineering MVP Workflow

```text
User registers
      ↓
Creates engineering organization
      ↓
Invites engineer
      ↓
Assigns role
      ↓
Creates client
      ↓
Creates project
      ↓
Assigns project team
      ↓
Creates project phases
      ↓
Creates tasks
      ↓
Uploads documents
      ↓
Creates design
      ↓
Reviews / approves design
      ↓
Schedules inspection
      ↓
Records inspection findings
      ↓
Records engineering time
      ↓
Creates invoice
      ↓
Records payment
      ↓
Closes project
      ↓
Audit history contains lifecycle
```

---

## 85. Development Phases

### Phase 0: Architecture Foundation

Deliver:

```text
Domain design
Database conventions
REST conventions
Authorization rules
Repository structure
Engineering workflows
```

### Phase 1: Shared Platform Core

Build:

```text
Auth
Users
Organizations
Organization professions
Membership invitations
Memberships
Roles
Permissions
Authorization
Audit
Outbox
```

### Phase 2: Engineering CRM

Build:

```text
engineering_clients
```

### Phase 3: Engineering Projects

Build:

```text
engineering_projects
engineering_project_members
engineering_project_phases
```

### Phase 4: Work Management

Build:

```text
engineering_tasks
engineering_sites
```

### Phase 5: Documents

Build:

```text
documents
document_versions
object storage
signed uploads
engineering document links
```

### Phase 6: Designs

Build:

```text
engineering_designs
engineering_design_versions
engineering_design_reviews
approval rules
credential-aware authorization
```

### Phase 7: Inspections

Build:

```text
engineering_inspections
engineering_inspection_findings
follow-ups
attachments
```

### Phase 8: Time and Billing

Build:

```text
engineering_time_entries
invoices
invoice_items
payments
```

### Phase 9: Notifications

Build:

```text
in-app notifications
email
worker processing
```

### Phase 10: Reporting

Initial reports:

```text
project status
overdue tasks
inspection status
billable time
revenue
outstanding invoices
```

---

## 86. Legal Expansion

Only after engineering proves the shared platform assumptions.

Build:

```text
Legal Client
    ↓
Matter
    ↓
Case
    ↓
Hearings / Deadlines / Documents
```

Do not redesign engineering around legal terminology.

Extract only genuinely reusable infrastructure.

---

## 87. Healthcare Expansion

Healthcare comes after:

- core platform is stable
- audit model is proven
- permission model is proven
- tenant isolation is tested
- retention and encryption strategies are defined

Healthcare should be treated as its own security and compliance workstream.

---

## 88. Deployment Environments

Use:

```text
development
testing
staging
production
```

Each environment has independent:

```text
database
object storage
secrets
queues
API keys
```

---

## 89. Initial Deployment Architecture

```text
CDN
 │
 ├── Engineering Web
 ├── Legal Web
 └── Healthcare Web

Load Balancer
      │
   Backend API
      │
      ├── PostgreSQL
      ├── Redis
      ├── Object Storage
      └── Queue
             │
          Workers
```

Prefer managed infrastructure where practical.

---

## 90. Backup Strategy

Database:

```text
automated backups
point-in-time recovery
tested restores
```

Object storage:

```text
versioning
retention policies
backup or replication where required
```

A backup strategy is incomplete until restoration is tested.

---

## 91. Migration Strategy

Use explicit numbered migrations.

Example:

```text
001_core_organizations
002_core_users
003_core_memberships
004_core_rbac
005_core_audit
006_engineering_clients
007_engineering_projects
008_engineering_project_members
009_engineering_phases
010_engineering_tasks
```

Do not use automatic ORM schema synchronization in production.

---

## 92. Technology Recommendation

Backend:

```text
TypeScript
NestJS or Fastify-based architecture
```

Database:

```text
PostgreSQL
```

ORM/query layer candidates:

```text
Prisma
Drizzle
Kysely
```

Frontend:

```text
React / Next.js
```

Queue:

```text
Redis + BullMQ
```

Storage:

```text
S3-compatible storage
```

Observability:

```text
OpenTelemetry
```

Containers:

```text
Docker
```

---

## 93. REST API Milestones

### Milestone 1: Platform Access

```http
POST /auth/register
POST /auth/login
POST /auth/refresh
GET  /me

POST /organizations
GET  /me/organizations

POST /membership-invitations
GET  /memberships

GET  /roles
POST /roles
GET  /permissions
```

Goal:

```text
Create account
↓
Create organization
↓
Invite team
↓
Assign roles
```

### Milestone 2: Engineering Clients

```http
POST  /engineering/clients
GET   /engineering/clients
GET   /engineering/clients/{id}
PATCH /engineering/clients/{id}
```

### Milestone 3: Engineering Projects

```http
POST  /engineering/projects
GET   /engineering/projects
GET   /engineering/projects/{id}
PATCH /engineering/projects/{id}

POST /engineering/projects/{id}/activate
POST /engineering/projects/{id}/close
```

### Milestone 4: Collaboration

```http
POST /engineering/projects/{id}/members
GET  /engineering/projects/{id}/members

POST /engineering/tasks
GET  /engineering/tasks
POST /engineering/tasks/{id}/complete
```

### Milestone 5: Sites and Documents

Build:

```text
engineering sites
signed file uploads
project document links
```

### Milestone 6: Designs and Inspections

Build:

```text
designs
reviews
approvals
inspections
findings
```

### Milestone 7: Commercial Workflows

Build:

```text
time entries
invoices
payments
reports
```

---

## 94. Architecture Rules to Freeze

1. REST is the primary frontend and integration API.
2. Base path is `/api/v1`.
3. GraphQL is not part of v1.
4. One shared backend platform.
5. Separate frontend application for each profession.
6. Each profession owns its database tables.
7. Shared modules contain infrastructure, not profession-specific semantics.
8. Every tenant-owned row has `organization_id`.
9. Tenant isolation is enforced by both application and database.
10. Authorization is always server-side.
11. Roles and professional credentials are different concepts.
12. Profession-specific permissions use namespaces.
13. PostgreSQL is the source of truth.
14. Files live in object storage.
15. Important business transitions use explicit REST command endpoints.
16. Important mutations are audited.
17. Domain events use a transactional outbox.
18. Background side effects run through workers.
19. Start as a modular monolith.
20. Do not start with microservices.
21. Do not replace proper domain modeling with JSON blobs.
22. Do not hard-delete important professional or financial records without explicit retention rules.
23. Database models and public API DTOs are separate contracts.
24. The frontend never determines authorization.
25. Healthcare receives stricter security treatment than ordinary CRM data.
26. Engineering is the first implemented vertical.
27. Legal follows after engineering validates the platform.
28. Healthcare follows after security and compliance requirements are explicitly designed.
29. OpenAPI is the source of truth for the REST contract.
30. Reconsider GraphQL only if a demonstrated client-composition problem justifies the added complexity.

---

## 95. Required Design Artifacts

Prepare and maintain:

```text
01_PROJECT_ARCHITECTURE.md
02_DATABASE_CONVENTIONS.md
03_AUTHORIZATION_MODEL.md
04_ENGINEERING_DOMAIN.md
05_ENGINEERING_DATABASE_SCHEMA.md
06_API_CONVENTIONS.md
07_ENGINEERING_API_SPEC.md
08_FRONTEND_ARCHITECTURE.md
09_SECURITY_MODEL.md
10_DEPLOYMENT_ARCHITECTURE.md
11_TESTING_STRATEGY.md
12_MVP_BACKLOG.md
13_OPENAPI.yaml
```

---

## 96. Recommended Implementation Order

```text
Foundation
   ↓
Authentication
   ↓
Organizations
   ↓
Memberships
   ↓
RBAC
   ↓
Engineering Clients
   ↓
Engineering Projects
   ↓
Project Team
   ↓
Tasks
   ↓
Sites
   ↓
Documents
   ↓
Designs
   ↓
Inspections
   ↓
Time Tracking
   ↓
Billing
   ↓
Notifications
   ↓
Reports
   ↓
Legal Vertical
   ↓
Healthcare Vertical
```

---

## 97. Final Design Position

The platform is not a generic management system with profession names painted on top.

It is:

```text
One Shared Platform
      │
      ├── Shared Identity
      ├── Shared Security
      ├── Shared Infrastructure
      ├── Shared Documents
      ├── Shared Financial Core
      ├── Shared Audit/Event Platform
      │
      ├── Engineering Product
      │   ├── Engineering Frontend
      │   ├── Engineering REST APIs
      │   └── Engineering Tables
      │
      ├── Legal Product
      │   ├── Legal Frontend
      │   ├── Legal REST APIs
      │   └── Legal Tables
      │
      └── Healthcare Product
          ├── Healthcare Frontend
          ├── Healthcare REST APIs
          └── Healthcare Tables
```

The system shares infrastructure where reuse is valuable while preserving independent domain models where professional workflows differ.