# ClientVault — Architecture Reference
## Multi-Tenant Client Asset & Credential Management

### Overview
ClientVault is a standalone multi-tenant platform where IT service providers (like CyberQA)
manage client infrastructure assets alongside the clients themselves. Both provider and
client can access the client's account, with granular sharing controls.

### Design Principles
1. **PortalQA-compatible schema** — uses `company_id` as tenant key (matches PortalQA v1.0)
2. **Merge-ready** — same DB naming conventions, same role priority system, same session patterns
3. **Provider + Client dual access** — three-tier roles with selective sharing
4. **Four asset classes** — Credentials, Documents, Hardware, Licenses
5. **Encryption where it matters** — passwords/secrets encrypted at rest; metadata searchable

### Directory Structure
```
clientvault/
├── config/
│   ├── app.php              # Constants, paths, environment
│   ├── db.php               # PDO singleton
│   ├── session.php          # Hardened session
│   └── security_headers.php # HTTP security headers
├── classes/
│   ├── Database.php         # PDO wrapper (extracted from config for autoloading)
│   ├── Encryption.php       # AES-256-GCM + PBKDF2
│   ├── Auth.php             # Multi-role auth with company context
│   ├── CSRF.php             # Token management
│   ├── RateLimiter.php      # Brute-force protection
│   ├── AuditLog.php         # Full action logging
│   ├── InputValidator.php   # Server-side validation
│   ├── AssetManager.php     # Base class for all asset types
│   ├── CredentialManager.php# Password/login CRUD
│   ├── DocumentManager.php  # Encrypted file storage
│   ├── HardwareManager.php  # Device inventory
│   ├── LicenseManager.php   # License keys + expiry tracking
│   ├── ClientManager.php    # Client (company) CRUD
│   ├── UserManager.php      # User management within companies
│   └── SharingManager.php   # Selective provider sharing controls
├── includes/
│   ├── bootstrap.php        # Init sequence
│   ├── auth_guard.php       # Protected page gate
│   └── functions.php        # Helpers
├── public/                  # Document root
│   ├── .htaccess
│   ├── index.php            # Login
│   ├── dashboard.php        # Role-aware dashboard
│   ├── credentials.php      # Password vault
│   ├── documents.php        # File manager
│   ├── hardware.php         # Device inventory
│   ├── licenses.php         # License tracker
│   ├── clients.php          # Client management (provider only)
│   ├── users.php            # User management
│   ├── sharing.php          # Sharing controls (client admin)
│   ├── audit.php            # Audit log
│   ├── download.php         # Authenticated file streamer
│   ├── api/
│   │   └── assets.php       # AJAX endpoints
│   ├── css/vault.css
│   ├── js/vault.js
│   └── partials/
│       ├── sidebar.php
│       └── header.php
├── storage/uploads/         # OUTSIDE webroot on production
├── logs/
├── backups/
├── cron/
│   ├── license_alerts.php   # Daily: check expiring licenses
│   └── cleanup.php          # Daily: rate limit + session cleanup
└── install.sql              # Full schema
```

### Role System (PortalQA-compatible priority)
| Role          | Priority | Scope                | Notes                        |
|---------------|----------|----------------------|------------------------------|
| Provider God  | 7        | All companies        | Taavi — above all            |
| Provider Admin| 6        | All companies        | CyberQA staff                |
| Provider Tech | 5        | Assigned companies   | Field techs, limited write   |
| Client Admin  | 3        | Own company only     | Client's IT manager          |
| Client User   | 2        | Own company, limited | Staff with view access       |
| Client Viewer | 1        | Shared items only    | Read-only, invited users     |

### Sharing Model
- **Default**: Provider sees ALL client assets (they manage the infrastructure)
- **Client can HIDE**: Client admin can mark specific items as "client-private"
  (e.g., personal passwords unrelated to managed infrastructure)
- **Client can SHARE**: Client admin can explicitly share items with specific
  provider users or roles
- **Sharing is per-asset**: Each credential, document, hardware item, or license
  has a `provider_visible` flag (default: true) and optional `shared_with` entries

### Encryption Strategy
- **Encrypted at rest**: credential passwords, secret keys, document files
- **Searchable (not encrypted)**: titles, categories, device names, serial numbers,
  license names — these need to be filterable/sortable
- **Encryption key**: Per-company key derived from a company master secret
  (set by provider during onboarding, shared with client admin)
- **Provider master key**: Can decrypt any company's data (recovery/support)

### PortalQA Merge Path
When merging into PortalQA v1.0:
1. Tables already use `company_id` — just add to existing DB
2. Role priorities 1-3 map to PortalQA's client-side roles
3. Add "Assets" to Portal Hub dropdown
4. Auth class extends PortalQA's existing session/role system
5. Sidebar items become conditional on license/module activation