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)

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:
```
"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.

4.0 KiB Raw Blame History