Newbie_CRM/database/DESIGN_DECISIONS.md

# CRM Database Schema — Enterprise RBAC + CRM

## Architecture Overview

Enterprise-grade PostgreSQL schema implementing **hierarchical Role-Based Access Control (RBAC)**
with a complete CRM system. Designed for production deployments with strict security requirements,
audit compliance, and scalability to millions of records.

---

## 1. Hierarchical RBAC Model

Four roles arranged in a strict hierarchy by `hierarchy_level` (lower = higher privilege):

| Role | Level | Authority |
|------|-------|-----------|
| **SUPER_ADMIN** | 1 | Unrestricted — create/delete users, assign roles, override all permissions |
| **ADMIN** | 2 | Operational — ban/suspend users, review reports, moderate activity. **Cannot create accounts.** |
| **SALES_USER** | 3 | CRM operations — leads, customers, opportunities, communications |
| **DEVELOPER** | 4 | Technical + CRM read access for post-sale project visibility |

### Enforcement via PostgreSQL Triggers

- **`enforce_create_user()`** (BEFORE INSERT ON users): Only SUPER_ADMIN (`hierarchy_level = 1`)
  can create new user accounts. Bootstrap case (`created_by IS NULL`) is allowed for initial setup.
- **`enforce_role_assignment()`** (BEFORE INSERT ON user_roles): Only SUPER_ADMIN can assign roles.
  Prevents privilege escalation by checking hierarchy levels.

### Permission Model

Granular permissions stored in `permissions` table with `(resource, action)` pairs.
`role_permissions` maps roles to permissions. The `has_permission(user_id, resource, action)`
function provides application-layer authorization checks.

---

## 2. Ban & Suspension System

Two separate tables for enforcement flexibility:

- **`banned_users`**: Permanent or time-limited bans. Supports reversal (by SUPER_ADMIN).
  Admins can create bans; SUPER_ADMIN can reverse or permanently delete banned users.
- **`suspended_users`**: Time-limited suspensions (always has expiry). Admins can create
  and lift suspensions.

Both tables are fully audited via dedicated trigger functions.

---

## 3. Session & Login Security

- **`sessions`**: Stores hashed session tokens with expiry. Only one active session per
  token hash.
- **`login_attempts`**: Captures every login attempt (successful or failed) with IP address
  and user agent. Used for brute-force detection and audit.
- Users have `failed_login_attempts` and `locked_until` for account lockout policies.

---

## 4. Password Security

- All passwords hashed with **bcrypt (cost factor 12)**
- `password_change_required` forces password change on first login (TRUE for all non-root
  test accounts)
- Password hashes are opaque to the database — validation is application-layer only

---

## 5. UUID Primary Keys

- All tables use `UUID PRIMARY KEY DEFAULT uuid_generate_v4()`
- Fixed UUIDs used for seed data and system entities for referential transparency
- Prevents enumeration attacks and supports distributed ID generation

---

## 6. Audit Trail

Every mutation is logged to `audit_logs` via `audit_trigger_function()`:

- Captures `(table_name, record_id, action, old_data, new_data, changed_by, ip_address)`
- Ban actions, suspension actions, and successful logins have dedicated audit triggers
- Indexed on `(table_name, record_id)` for per-record lookup

Dedicated audit views:
- `v_active_bans` — Currently active bans with user details
- `v_active_suspensions` — Currently active suspensions
- `v_user_permissions` — Flattened permission report per user

---

## 7. Third Normal Form (3NF)

Customer model uses the **discriminator pattern**:

```
customers (parent — shared columns: status, owner, tags, score)
  ├── customer_type = 'individual' → individual_customers
  └── customer_type = 'company'    → company_customers
```

All lookup tables are normalized. Contact information, addresses, and notes are
separate 1:N child tables.

---

## 8. Indexing Strategy

- **Core indexes**: FK columns, status/sort/date columns, unique constraints
- **Partial indexes**: `WHERE deleted_at IS NULL` on soft-delete tables,
  `WHERE is_active = TRUE` on bans/suspensions, `WHERE due_date < NOW()` on overdue invoices
- **Full-text search**: GIN indexes on customers, leads, products, communications, tasks
- **Composite indexes**: Common query patterns (e.g., `opportunities(owner_id, stage_id)`)

---

## 9. Soft Delete

- `deleted_at TIMESTAMPTZ` on all business tables
- Partial unique indexes ignore soft-deleted rows (e.g., `WHERE deleted_at IS NULL`)
- Audit logs capture the full row snapshot before soft-delete

---

## 10. Test Accounts

| Username | Password | Role |
|----------|----------|------|
| `superadmin_demo` | `[REDACTED]` | SUPER_ADMIN |
| `admin_demo` | `[REDACTED]` | ADMIN |
| `sales_demo` | `[REDACTED]` | SALES_USER |
| `dev_demo` | `[REDACTED]` | DEVELOPER |

---

## 11. Migration Instructions

```bash
# Create database
psql -U postgres -c "CREATE DATABASE crm;"

# Run full migration
psql -U postgres -d crm -f database/migrations/run_all.sql

# Or step by step:
psql -U postgres -d crm -f database/migrations/001_schema.sql
psql -U postgres -d crm -f database/migrations/002_seed.sql
```

---

## 12. Security Rules Summary

| Rule | Enforcement |
|------|-------------|
| Only SUPER_ADMIN creates accounts | Trigger `trg_enforce_create_user` |
| Only SUPER_ADMIN assigns roles | Trigger `trg_enforce_role_assignment` |
| No privilege escalation | Level check in `enforce_role_assignment()` |
| bcrypt password hashing | Application-layer (cost=12) |
| Unique usernames/emails | Partial unique indexes |
| Force password change on first login | `password_change_required` column |
| Audit every login/logout | Trigger `trg_audit_login` on `login_attempts` |
| Audit every ban action | Trigger `trg_audit_ban` on `banned_users` |
| Audit every suspension action | Trigger `trg_audit_suspension` on `suspended_users` |