Docs: Create project rules.md, architecture.md, memory.md, and phases.md documentation

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

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.

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.

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.