73 lines
4.0 KiB
Markdown
73 lines
4.0 KiB
Markdown
# 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.
|