Docs
AI Docs
Crystal Agents
Implementation Plan: B2 Markdown Document Management System

Implementation Plan: B2 Markdown Document Management System

This document outlines the design and implementation plan for the Crystal Document Center, a secure, high-performance web UI integrated into the Crystal Dashboard. It allows team members to upload, search, navigate, and view markdown files (PRDs, completion reports, AI validation reports, etc.) organized by Project and Team Member within a protected Backblaze B2 bucket (crystal-ai-docs).

1. Directory Structure & B2 Object Keys

We will organize files in the crystal-ai-docs bucket using the following key prefix structure:

[project-id]/[team-member-name]/[filename].md

Examples:

  • erpcrystal-mfg/john-doe/prd-inventory-v1.md
  • erpcrystal-chs/jane-smith/completion-report-june.md

2. Technical Architecture

To keep the system lightweight and avoid adding bulky python dependencies (like boto3 or b2sdk), we will implement a self-contained, native Backblaze B2 API client using Python’s standard library (urllib.request, json, hmac).

+------------------+             +--------------------------+             +-----------------------+
|   Web Browser    |  ========>  | Dashboard Server (Py)    |  ========>  | Backblaze B2 API      |
|   (Dashboard UI) |  <========  | (BaseHTTPRequestHandler) |  <========  | (REST JSON API)       |
+------------------+             +--------------------------+             +-----------------------+

Key Configuration Variables (.env)

We will define the following credentials in the .env file:

# Backblaze B2 Storage Settings
CRYSTAL_B2_APPLICATION_KEY_ID=your_b2_key_id
CRYSTAL_B2_APPLICATION_KEY=your_b2_application_key
CRYSTAL_B2_BUCKET_NAME=crystal-ai-docs

3. Python Backend Implementation

We will add a clean, well-tested module tools/b2_client.py and a routing file dashboard/routes/docs.py.

A. tools/b2_client.py

A class-based Backblaze B2 API client utilizing standard library utilities:

  • authorize(): Authenticates using App Key / ID and retrieves token and endpoint URLs.
  • get_bucket_id(): Fetches the bucketId for the configured bucket name.
  • list_files(): Lists all file names and metadata inside the bucket.
  • upload_file(path_key, content_bytes): Obtains an upload URL and uploads file bytes.
  • download_file(path_key): Downloads the contents of a private file.
  • delete_file(path_key): Deletes a file from B2.

B. dashboard/routes/docs.py

Routes added to the dashboard server:

  • GET /docs: Lists files, parses the directory structure, and renders the index page.
  • GET /docs/view?file=...: Fetches file contents from B2 and returns it.
  • POST /docs/upload: Parses the uploaded file and uploads it to B2 under [project]/[member]/[filename].
  • POST /docs/delete: Deletes a file.

4. UI / UX Design System

The user interface will be built with rich aesthetics, responsive grid layouts, glassmorphism, and smooth animations using CSS, styled similarly to the main Crystal Dashboard.

A. Navigation & Search (Left Panel)

  • Unified Search Bar: A beautiful search bar with a quick filter for projects, team members, and file names.
  • Tree Navigation: An interactive directory structure:
    • Projects (collapsible folder icon)
      • Team Members (sub-folder icon)
        • Markdown Files (document icon with file size)

B. Upload Panel (Right Panel - Default View)

  • A drag-and-drop file target area.
  • Form inputs:
    • Project Select: Dropdown of existing projects with the ability to type/create a new one.
    • Team Member Select: Dropdown of existing team members with the ability to type/create a new one.
  • Sleek upload button with progress animation.

C. File View Panel (Right Panel - File View)

  • Header: File name, breadcrumbs (Project > Member), file size, and upload date.
  • Actions: “Download Raw” and “Delete File” buttons.
  • Content Area: Markdown renderer:
    • Employs marked.js (CDN) for fast, compliant markdown parsing in the browser.
    • Employs Prism.js (CDN) for code syntax highlighting.
    • Custom styling for markdown elements (h1, h2, lists, code blocks, tables, blockquotes) matching the dashboard’s premium dark mode theme.

5. Development Steps

  1. Step 1: Configuration: Add B2 variables to .env and update AppConfig to support them.
  2. Step 2: API Client: Implement and unit test the native B2Client in tools/b2_client.py.
  3. Step 3: Route Logic: Implement /docs, /docs/view, /docs/upload, /docs/delete in dashboard/routes/docs.py.
  4. Step 4: Request Handler Integration: Map routes in dashboard/app.py.
  5. Step 5: Frontend Design: Build the HTML/CSS template with client-side search, collapsing folders, uploading, and marked.js parsing.
  6. Step 6: Validation: Run local tests and verify everything uploads and renders perfectly.
Feature Get Intelligent ResponsesOkara