# System Architecture

This document details the system design, relational database models, folder structure, API routing, and security measures of the Tech4Biz Channel Partner Portal.

---

## 1. Directory Structure

The project is structured as a monorepo containing distinct frontend and backend directories:
* **`Channel-Frontend/`**: Vite + React + TypeScript web application.
* **`Channel-Backend/`**: Node.js + Express + TypeScript API server using Prisma ORM.
* **`minio-seed/`**: Repository seed files uploaded to the private S3 bucket on initialization.

---

## 2. Database Design (Prisma PostgreSQL Schema)

```mermaid
erDiagram
    Organization ||--o{ User : contains
    Organization ||--o{ SharedAsset : has
    User ||--o{ LegalAcceptance : signs
    User ||--o{ AuditLog : acts
    User ||--o{ SharedAsset : has
    User ||--o{ DownloadRequest : makes
    Asset ||--o{ SharedAsset : shared
    Asset ||--o{ DownloadRequest : requested
    Folder ||--o{ Asset : contains
    LegalDocument ||--o{ LegalAcceptance : tracks
    AssetGroup }|--|{ Asset : groups
```

### Models Summary
* **`Organization`**: Tenant containers mapping partner companies.
* **`User`**: Admin and Partner users. Supports onboarding status (`PENDING_ONBOARDING`, `APPROVED`, etc.), multi-factor authentication configurations (`mfaEnabled`, `mfaSecret`), and legal document associations (`assignedNdaId`, `assignedMsaId`).
* **`Asset`**: Physical document files, external web URLs, and Case Studies.
* **`SharedAsset`**: Connects assets to organizations or individual users to restrict visibility.
* **`DownloadRequest`**: Tracks approvals for un-downloadable assets.
* **`Folder`**: Hierarchy container for assets.
* **`LegalDocument`**: NDA / MSA legal templates versioned by admins.
* **`LegalAcceptance`**: Cryptographic evidence of legal sign-off (contains signer IP, signature hash, and base64 signature images).
* **`AuditLog`**: Compliance tracking logs.
* **`BlogPost`**: Internal blog CMS posts.
* **`AssetGroup`**: Dynamic tagging groups for catalog organization.

---

## 3. Storage Architecture (MinIO Private S3)

To ensure secure, scalable, and isolated asset delivery, files are hosted in a private **MinIO** S3 bucket:
* **Upload Pipeline**: Express backend receives multipart file uploads using `multer`, uploads the buffer directly to MinIO using `@aws-sdk/client-s3`, and stores a `/uploads/filename` relative URL path in the Postgres `Asset` table.
* **Pre-Signed URLs**: Asset URLs are **never public**. When rendering or downloading files, the backend generates short-lived, pre-signed S3 URLs (expiring in 5 minutes) via `@aws-sdk/s3-request-presigner`.
* **Deletion Lifecycle**: When deleting an asset database record, `AssetService` intercepts the URL, detects S3 relative paths, and issues a `DeleteObjectCommand` to permanently clean up the physical file from the storage bucket.

---

## 4. Document Rendering Pipeline

To ensure high-fidelity previews without exposing documents to third-party services:
* **PDF Previews**: Rendered natively in the browser via PDF.js on a hidden `<canvas>`, exporting a high-performance Base64 JPEG URL.
* **Word Documents (`.docx`)**: Downloaded as `arraybuffer` and parsed client-side using `docx-preview` inside A4 aspect containers.
* **Spreadsheets (`.xlsx`, `.xls`, `.csv`)**: Parsed client-side via SheetJS (`xlsx`) and rendered as HTML tables. Formatted with explicit dark slate text styles to remain readable regardless of the layout's light/dark mode theme.
* **PowerPoint (`.pptx`, `.ppt`)**: Embedded via Microsoft Office Online Viewer in staging/production, falling back to dynamic mockup cards on localhost.

---

## 5. Security & Access Controls
* **Content Security Policy (CSP)**: Customized in Express app helmet headers to permit iframe sandbox integrations from:
  ```json
  "frame-ancestors": ["'self'", "http://localhost:5173", "http://localhost:5000"]
  ```
* **Legal Acceptance Gates**: Onboarding status `PENDING_ONBOARDING` restricts partner UI routing, requiring users to complete assigned legal agreement forms before viewing assets.