diff --git a/architecture.md b/architecture.md new file mode 100644 index 0000000..2be259d --- /dev/null +++ b/architecture.md @@ -0,0 +1,72 @@ +# 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 ``, 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. diff --git a/memory.md b/memory.md new file mode 100644 index 0000000..7fb8abd --- /dev/null +++ b/memory.md @@ -0,0 +1,35 @@ +# Developer Memory Log + +This document records the exact state of the project, completed features, solved bugs, and historical changes to maintain continuity. + +--- + +## 1. Core Completed Features + +### A. Onboarding Legal Skip & MFA Control +* **Onboarding Skip**: Implemented "None (No agreement required)" legal options. When a partner is invited or updated with no NDA/MSA requirement, the backend `AuthService` automatically bypasses signing steps and sets the user's status to `APPROVED`. +* **MFA Toggle**: Added `mfaEnabled` options inside the partner invitation modal, partner editing forms, and backend API routes. + +### B. Client-Side Document Previews +* **Word Document Preview**: Integrated `docx-preview` to parse raw OpenXML array buffers and render them in-browser. +* **Spreadsheet & CSV Preview**: Integrated SheetJS (`xlsx`) to parse spreadsheet buffers and generate clean HTML cell tables. +* **Online Preview Button**: Enabled online preview buttons (Eye icon) for CSV files and text/code files by expanding the `isRenderable` utility in `AssetCard.tsx`. + +### C. Responsive Full-Bleed Thumbnails +* **Word & Spreadsheet Card Thumbnails**: Replaced static placeholders with dynamic rendered previews of the first page/sheet. +* **Responsive Scaling**: Integrated a React `ResizeObserver` hook inside `DocxThumbnail.tsx` and `SpreadsheetThumbnail.tsx` to automatically calculate scaling factor based on card width, making cards fit their containers perfectly instead of sticking to the top-left corner. + +### D. Clean Admin Deletion +* **S3 Deletion Hook**: Updated backend `AssetService.deleteAsset` to detect files under `/uploads/` and dispatch a `DeleteObjectCommand` to the MinIO container bucket, cleaning up disk space on deletion. + +--- + +## 2. Key Resolved Bugs + +### A. CSV Text Preview Bypass +* **Symptom**: CSV files were being treated as plain text files, rendering as comma-separated text blocks in a code viewport. +* **Resolution**: Excluded `.csv` files and mime-types from the `isTextOrCodeAsset` filter inside `AssetViewerModal.tsx`. This routed them correctly to the SheetJS spreadsheet parser. + +### B. Dark Mode Cell Invisible Text +* **Symptom**: In dark mode, spreadsheet/CSV cells rendered as blank grids because text inherited the light mode/system white text color. +* **Resolution**: Added explicit `.excel-thumbnail-container table { color: #0f172a }` and `.excel-preview-container table { color: #0f172a }` CSS rules to override dark mode layout text colors and keep tables fully readable. diff --git a/phases.md b/phases.md new file mode 100644 index 0000000..d3b0fd0 --- /dev/null +++ b/phases.md @@ -0,0 +1,28 @@ +# Project Phases & Roadmap + +This document structures past achievements and maps future development phases for the Tech4Biz Channel Partner Portal. + +--- + +## Phase 1: Secure Asset Library & Onboarding Gateway (COMPLETED) +* **Secure Client-Side Previews**: Built browser-native preview engines for Word, PDF, Excel, and CSV files, bypassing external online view dependencies. +* **Responsive Full-Bleed Thumbnails**: Integrated `ResizeObserver` to dynamically scale dynamic first-page/sheet previews to the size of the catalog grid cards. +* **Onboarding Legal Skip**: Created a fallback route allowing administrators to skip legal NDAs/MSAs for trusted partners. +* **MFA Security Gates**: Added MFA configuration toggles to both backend user registration and frontend administration panels. +* **Disk/Storage Cleanup**: Integrated automatic MinIO file deletion routines into the administrative delete-asset workflow. + +--- + +## Phase 2: Multi-Company & Multi-Branch Organization Segregation (UPCOMING) +* **Hierarchical Company Branches**: Extend `Organization` model to support sub-branches or multi-company profiles under a single parent entity. +* **Rigorous Multi-Tenancy Scopes**: Refine database query interceptors in backend service layers to verify that users can only search, discover, or download assets explicitly tagged/shared to their current branch or organization hierarchy. +* **Organization Admin Scopes**: Introduce organization-specific admins who can invite members and review download requests within their own company boundaries without global system privileges. + +--- + +## Phase 3: Client-Side Recommendations Engine (UPCOMING) +* **Personalized Asset Suggestions**: Implement an asset recommendation widget on the partner dashboard recommending resources based on: + * User's partner group classification. + * Popularity (highest download counts). + * Recently uploaded assets within matching folder categories. +* **Activity-Based Feeds**: Display a "Recommended for You" section utilizing tag matching algorithms on the client catalog homepage. diff --git a/rules.md b/rules.md new file mode 100644 index 0000000..4095509 --- /dev/null +++ b/rules.md @@ -0,0 +1,37 @@ +# Project Development Rules + +This document outlines the strict guidelines and standards for pair-programming and code development across sessions. + +--- + +## 1. Documentation Synchronization Rule (CRITICAL) +Whenever any feature, file layout, database model, API endpoint, component, or system logic is created, modified, or deleted: +* You **MUST** update the relevant sections of `architecture.md`, `memory.md`, and `phases.md` in the same developer turn/commit. +* Documentation must match the codebase exactly; there must be **zero** discrepancy, assumptions, or trailing documentation debt. + +--- + +## 2. Coding & Technical Standards + +### A. Environment Variable Safety +* Do **not** hardcode API endpoints, JWT secrets, S3 bucket names, or MinIO endpoints. +* Always read configurations from `.env` (backend uses `process.env.VAR`, frontend uses `import.meta.env.VITE_VAR`). + +### B. Security & Iframe Embedding Policies +* Keep Express security configurations using `helmet` aligned. +* **Frameguard must remain disabled** (`frameguard: false`) to allow authorized parent components to embed secure previews. +* Content Security Policy (CSP) must contain `"frame-ancestors": ["'self'", "http://localhost:5173", "http://localhost:5000"]` to prevent browsers from blocking localized iframe previews. + +### C. Client-Side Document Previews & Thumbnails +* **Client-Side Processing**: Previews and thumbnails must run client-side. Use `docx-preview` for `.docx`, SheetJS (`xlsx`) for spreadsheets (`.xlsx`, `.xls`, `.csv`), and `PDF.js` for `.pdf`. +* **Dark Mode Styling Safeguards**: Always force an explicit dark text color (`color: #0f172a`) inside bare spreadsheet HTML containers (such as `.excel-thumbnail-container` or `.excel-preview-container`) so that cell text is readable even if the application layout is in dark mode. +* **Dynamic Full-Bleed Scaling**: Card thumbnails for Word and spreadsheet components must scale dynamically using a `ResizeObserver` based on the parent card width: + ```typescript + scale = parentWidth / innerDocumentWidth + ``` +* **Legacy Format Fallbacks**: For formats where client-side rendering is impossible (such as legacy OLE binary `.doc` and `.ppt` formats), provide gorgeous, type-aware cover mockup views. + +### D. File Cleanups upon Deletion +* Always delete physical S3 objects when their database references are deleted: + * In the backend asset controllers/services, verify if the asset URL starts with `/uploads/`. + * If so, invoke `DeleteObjectCommand` on the S3 `s3Client` to remove the binary object from the MinIO bucket, preventing orphaned storage bloat.