Skip to content
HeliosDB HeliosDB Full

HeliosDB Documentation Directory Guide

HeliosDB Documentation Directory Guide

Version: 1.0 Created: November 17, 2025 Purpose: Reference guide for placing new documentation files

Overview

This guide provides a comprehensive list of all documentation directories with their purpose and usage guidelines. Always consult this guide before creating new documentation files.

Quick Reference

DirectoryPurposeWhen to Use
docs/reports/Reports and summariesCompletion reports, session reports, progress tracking
docs/planning/Planning documentsRoadmaps, execution plans, implementation strategies
docs/analysis/Analysis reportsSecurity audits, performance analysis, codebase analysis
docs/architecture/Architecture docsSystem design, architecture decisions, technical design
docs/guides/User and developer guidesHow-to guides, tutorials, documentation guidelines
docs/features/Feature documentationFeature-specific implementation docs
docs/protocol/Protocol specificationsWire protocols, API specifications
docs/heliosdb-lite/HeliosDB Lite docsLite variant planning, compatibility, analysis
docs/quick-starts/Quick start guidesGetting started, deployment guides, quick references
docs/reference/Reference documentationAPI reference, feature index, technical reference
docs/implementation/Implementation reportsBuild reports, compilation status, integration reports
docs/testing/Testing documentationTest strategies, coverage reports, quality assurance
docs/ip/Intellectual propertyPatent analysis, innovation reports, IP compliance
docs/archive/Historical documentsArchived reports, deprecated docs, historical summaries

Detailed Directory Structure

/docs/reports - Reports and Summaries

Reports documenting completed work, progress, and sessions.

/docs/reports/distributed execution

  • Purpose: Multi-agent coordination and collective intelligence session reports
  • Use When: Documenting distributed execution swarm sessions, multi-agent collaboration
  • Contents: Session summaries, swarm execution reports, collective decisions
  • Naming: HIVE_MIND_[TOPIC]_[STATUS].md

/docs/reports/sessions

  • Purpose: Daily/weekly session summaries and progress metrics
  • Use When: Recording session work, daily/weekly progress
  • Contents: Session reports, day/week summaries, metrics
  • Naming: SESSION_[DESCRIPTION]_[DATE].md, DAY[N]_*.md, WEEK[N]_*.md

/docs/reports/agents

  • Purpose: Individual agent execution reports and deliverables
  • Use When: Documenting work by specific agents
  • Contents: Agent completion reports, agent deliverables
  • Naming: AGENT[N]_WEEK[N]_[DESCRIPTION].md
  • Subdirectories:
    • summaries/ - Brief agent summaries and status updates

/docs/reports/phase

  • Purpose: Phase completion reports and milestone tracking
  • Use When: Documenting phase completions, milestone achievements
  • Contents: Phase 1-5 reports, month/week progress tracking
  • Naming: PHASE[N]_[DESCRIPTION].md, MONTH[N]_*.md

/docs/reports/completion

  • Purpose: Feature and implementation completion reports
  • Use When: Documenting completed features, integrations, implementations
  • Contents: Feature completion reports, TODO resolution reports
  • Naming: [FEATURE_NAME]_COMPLETION_REPORT.md

📋 /docs/planning - Planning Documents

Strategic planning, roadmaps, and execution plans.

Main Planning Directory

  • Purpose: High-level planning documents and execution strategies
  • Use When: Creating roadmaps, execution plans, strategic plans
  • Contents: Roadmaps, implementation plans, execution strategies
  • Naming: [SCOPE]_[TYPE]_PLAN.md, ROADMAP_*.md
  • Examples:
    • V7_0_COMPLETE_ROADMAP.md
    • PHASE3_EXECUTION_PLAN.md
    • FEATURE_IMPLEMENTATION_PLAN.md

/docs/analysis - Analysis Reports

Detailed analysis of code, performance, and security.

/docs/analysis/codebase

  • Purpose: Code analysis, gap analysis, consolidation reports
  • Use When: Analyzing codebase structure, identifying gaps, planning consolidation
  • Contents: Package analysis, gap analysis, consolidation reports, code quality
  • Naming: [TOPIC]_ANALYSIS_REPORT.md

/docs/analysis/performance

  • Purpose: Performance benchmarks, optimization analysis, SIMD analysis
  • Use When: Documenting performance studies, benchmark results, optimization strategies
  • Contents: Benchmark analysis, SIMD optimization, performance regression analysis
  • Naming: [FEATURE]_PERFORMANCE_ANALYSIS.md

/docs/analysis/security

  • Purpose: Security audits, vulnerability assessments, security fixes
  • Use When: Documenting security reviews, audits, vulnerability fixes
  • Contents: Security audits, WASM analysis, SQL injection protection, unwrap analysis
  • Naming: [TOPIC]_SECURITY_ANALYSIS.md

🏗 /docs/architecture - Architecture Documentation

System architecture and design decisions.

Main Architecture Directory

  • Purpose: High-level system architecture and design
  • Use When: Documenting system design, architecture decisions, technical architecture
  • Contents: Architecture diagrams, design documents, system architecture
  • Naming: [COMPONENT]_ARCHITECTURE.md

Version-Specific Subdirectories

  • /docs/architecture/v5.x/ - Version 5.x architecture
  • /docs/architecture/v6.0/ - Version 6.0 architecture
  • /docs/architecture/v7.0/ - Version 7.0 architecture

📚 /docs/guides - User and Developer Guides

How-to guides, tutorials, and documentation guidelines.

/docs/guides/user

  • Purpose: End-user documentation and tutorials
  • Use When: Creating user-facing documentation, tutorials, how-to guides
  • Contents: User guide index, SQL guides, feature tutorials
  • Naming: [FEATURE]_USER_GUIDE.md

/docs/guides/developer

  • Purpose: Developer documentation and guidelines
  • Use When: Documenting development guidelines, best practices, protocols
  • Contents: Feature development protocol, best practices, contributing guidelines
  • Naming: [TOPIC]_GUIDELINES.md, [TOPIC]_PROTOCOL.md
  • Key Files:
    • FEATURE_DEVELOPMENT_PROTOCOL.md - Protocol for new features
    • DOCUMENTATION_DIRECTORY_GUIDE.md - This file
    • DOCUMENTATION_ORGANIZATION_GUIDELINES.md - Organization rules

/docs/features - Feature Documentation

Feature-specific implementation documentation.

Feature Subdirectories

Organized by feature name:

  • /docs/features/mvcc/ - MVCC implementation docs
  • /docs/features/transactions/ - Transaction handling docs
  • /docs/features/indexing/ - Index management docs
  • /docs/features/[feature-name]/ - Other feature-specific docs

Use When: Creating detailed documentation for specific features Contents: Implementation details, design decisions, API documentation Naming: [FEATURE]_[ASPECT].md

🔌 /docs/protocol - Protocol Documentation

Wire protocols and API specifications.

Main Protocol Directory

  • Purpose: Protocol specifications and integration guides
  • Use When: Documenting wire protocols, API specifications, protocol compatibility
  • Contents: Cassandra/PostgreSQL compatibility, protocol specs, wire protocol docs
  • Naming: [PROTOCOL]_SPECIFICATION.md, [PROTOCOL]_COMPATIBILITY.md

💼 /docs/heliosdb-lite - HeliosDB Lite Documentation

Documentation for HeliosDB Lite standalone variant.

/docs/heliosdb-lite/planning

  • Purpose: Lite implementation plans and specifications
  • Use When: Planning Lite features, compatibility, implementation strategies
  • Contents: Phase 3 plans, SQL wrappers, Product Quantization specs
  • Naming: HELIOSDB_LITE_[FEATURE]_[TYPE].md

/docs/heliosdb-lite/analysis

  • Purpose: Lite compatibility analysis and evaluation
  • Use When: Analyzing Lite→Full compatibility, feature evaluation
  • Contents: Compatibility analysis, model evaluation, hybrid storage analysis
  • Naming: HELIOSDB_LITE_[TOPIC]_ANALYSIS.md

/docs/heliosdb-lite/reference

  • Purpose: Lite reference documentation and indices
  • Use When: Creating master indices, reference guides for Lite
  • Contents: Phase indices, master references
  • Naming: HELIOSDB_LITE_[TOPIC]_INDEX.md

/docs/quick-starts - Quick Start Guides

Getting started guides and quick references.

Main Quick Starts Directory

  • Purpose: Quick start guides and deployment guides
  • Use When: Creating getting started docs, deployment guides, quick references
  • Contents: Feature quick starts, deployment guides, quick reference cards
  • Naming: [FEATURE]_QUICK_START.md, [TOPIC]_QUICK_REFERENCE.md

📖 /docs/reference - Reference Documentation

Technical reference and API documentation.

Main Reference Directory

  • Purpose: API reference, feature indices, technical specifications
  • Use When: Creating API docs, feature indices, technical references
  • Contents: API reference, feature index, performance docs, innovation docs
  • Naming: [COMPONENT]_API_REFERENCE.md, [TOPIC]_INDEX.md

/docs/implementation - Implementation Reports

Build reports and implementation status.

Main Implementation Directory

  • Purpose: Build reports, compilation status, integration reports
  • Use When: Documenting build status, compilation results, implementation checklists
  • Contents: Build reports, compilation summaries, integration status
  • Naming: [COMPONENT]_IMPLEMENTATION_REPORT.md

🧪 /docs/testing - Testing Documentation

Test strategies, coverage, and quality assurance.

Main Testing Directory

  • Purpose: Test coverage reports, test strategies, QA documentation
  • Use When: Documenting test plans, coverage reports, quality assurance
  • Contents: Test strategies, coverage reports, quality metrics
  • Naming: [COMPONENT]_TEST_REPORT.md, TEST_STRATEGY.md

/docs/ip - Intellectual Property

Patent analysis and innovation documentation.

Main IP Directory

  • Purpose: Patent analysis, innovation reports, IP compliance
  • Use When: Documenting potential patents, innovation analysis, IP compliance
  • Contents: Patent reports, innovation analysis, prior art research
  • Naming: [FEATURE]_PATENT_ANALYSIS.md, [TOPIC]_INNOVATION_REPORT.md

/docs/ip/reports

  • Purpose: Detailed IP analysis reports
  • Contents: Weekly innovation reports, patent research

/docs/archive - Historical Documentation

Archived and deprecated documentation.

/docs/archive/2025-11/

  • Purpose: November 2025 archived materials
  • Contents: Historical reports, deprecated docs, reorganization summaries
  • Subdirectories:
    • reorganization/ - Reorganization summaries and reports

Use When: Archiving historical documents, preserving deprecated content Note: Each archive directory should have a README.md explaining contents

/docs/benchmarks - Benchmark Documentation

Benchmark results and analysis.

/docs/benchmarks/results

  • Purpose: Benchmark execution results
  • Contents: Performance benchmarks, comparison reports

/docs/benchmarks/results/archive

  • Purpose: Historical benchmark data
  • Contents: Archived benchmark results

Placement Decision Tree

Use this decision tree to determine where to place new documentation:

Is it a REPORT?
├─ Yes → Is it about a completed feature/implementation?
│  ├─ Yes → docs/reports/completion/
│  ├─ No → Is it a session/daily/weekly report?
│  │  ├─ Yes → docs/reports/sessions/
│  │  ├─ No → Is it a distributed execution/swarm report?
│  │  │  ├─ Yes → docs/reports/distributed execution/
│  │  │  └─ No → Is it a phase/milestone report?
│  │  │     ├─ Yes → docs/reports/phase/
│  │  │     └─ No → Is it agent-specific?
│  │  │        ├─ Yes → docs/reports/agents/
│  │  │        └─ No → docs/reports/
│  └─ No → Continue...


Is it a PLANNING document?
├─ Yes → Is it HeliosDB Lite specific?
│  ├─ Yes → docs/heliosdb-lite/planning/
│  └─ No → docs/planning/
└─ No → Continue...


Is it ANALYSIS?
├─ Yes → What type?
│  ├─ Security → docs/analysis/security/
│  ├─ Performance → docs/analysis/performance/
│  ├─ Codebase → docs/analysis/codebase/
│  └─ Lite Compatibility → docs/heliosdb-lite/analysis/
└─ No → Continue...


Is it ARCHITECTURE?
├─ Yes → docs/architecture/[version]/
└─ No → Continue...


Is it a USER/DEVELOPER GUIDE?
├─ Yes → Is it for users or developers?
│  ├─ Users → docs/guides/user/
│  └─ Developers → docs/guides/developer/
└─ No → Continue...


Is it FEATURE-SPECIFIC?
├─ Yes → docs/features/[feature-name]/
└─ No → Continue...


Is it a PROTOCOL/API spec?
├─ Yes → docs/protocol/
└─ No → Continue...


Is it a QUICK START guide?
├─ Yes → docs/quick-starts/
└─ No → Continue...


Is it REFERENCE documentation?
├─ Yes → Is it Lite-specific?
│  ├─ Yes → docs/heliosdb-lite/reference/
│  └─ No → docs/reference/
└─ No → Continue...


Is it about TESTING?
├─ Yes → docs/testing/
└─ No → Continue...


Is it about IMPLEMENTATION status?
├─ Yes → docs/implementation/
└─ No → Continue...


Is it IP/PATENT related?
├─ Yes → docs/ip/
└─ No → Continue...


Is it HISTORICAL/DEPRECATED?
├─ Yes → docs/archive/[date]/
└─ No → Ask for guidance or use docs/

Naming Conventions

General Rules

  1. Use UPPERCASE_WITH_UNDERSCORES.md for markdown files
  2. Use descriptive names that indicate content
  3. Include version/date/phase when relevant
  4. Be consistent within each directory

Specific Patterns

Reports:

  • Session: SESSION_[DESCRIPTION]_[DATE].md
  • Phase: PHASE[N]_[DESCRIPTION].md
  • Week: WEEK[N]_[DESCRIPTION].md
  • Agent: AGENT[N]_WEEK[N]_[DESCRIPTION].md
  • Completion: [FEATURE]_COMPLETION_REPORT.md

Planning:

  • Roadmap: ROADMAP_[VERSION].md or V[N]_[N]_[DESCRIPTION]_ROADMAP.md
  • Plan: [SCOPE]_[TYPE]_PLAN.md

Analysis:

  • [TOPIC]_ANALYSIS_REPORT.md
  • [COMPONENT]_[TYPE]_ANALYSIS.md

Architecture:

  • [COMPONENT]_ARCHITECTURE.md
  • [SYSTEM]_DESIGN.md

Guides:

  • [TOPIC]_GUIDE.md
  • [FEATURE]_TUTORIAL.md

HeliosDB Lite:

  • Always prefix with HELIOSDB_LITE_
  • HELIOSDB_LITE_[FEATURE]_[TYPE].md

Common Mistakes to Avoid

❌ Don’t Do This

  • Placing files in project root (except README, CLAUDE.md, etc.)
  • Creating files in docs/ root (use subdirectories)
  • Using inconsistent naming conventions
  • Creating duplicate files in multiple locations
  • Ignoring the DOCUMENTATION_INDEX.md structure

Do This Instead

  • Always use appropriate subdirectories
  • Follow naming conventions
  • Check for existing files before creating new ones
  • Consult this guide when uncertain
  • Update indices when adding significant documentation

Quick Checklist

Before creating a new documentation file, verify:

  • Determined correct directory using decision tree
  • Checked for existing similar documentation
  • Followed naming conventions for that directory
  • File is not in root or docs root
  • HeliosDB Lite docs have proper prefix
  • Archive files are in archive/ with README
  • Updated relevant index files if needed

Examples

Example 1: Feature Completion Report

Content: Report documenting completion of MVCC feature Location: docs/reports/completion/MVCC_COMPLETION_REPORT.md Reasoning: Completion report goes in reports/completion/

Example 2: Security Analysis

Content: Analysis of SQL injection vulnerabilities Location: docs/analysis/security/SQL_INJECTION_ANALYSIS_REPORT.md Reasoning: Security analysis goes in analysis/security/

Example 3: Implementation Plan

Content: Plan for implementing Phase 3 features Location: docs/planning/PHASE3_IMPLEMENTATION_PLAN.md Reasoning: Planning document goes in planning/

Example 4: Lite Compatibility

Content: Analysis of Lite→Full compatibility Location: docs/heliosdb-lite/analysis/HELIOSDB_LITE_COMPATIBILITY_ANALYSIS.md Reasoning: Lite-specific analysis with proper prefix

Example 5: User Guide

Content: How to use vector search feature Location: docs/guides/user/VECTOR_SEARCH_USER_GUIDE.md Reasoning: User-facing guide goes in guides/user/

Maintenance

When to Update This Guide

  • Adding new documentation directories
  • Changing directory purposes
  • Reorganizing documentation structure
  • Significant directory structure changes

How to Update

  1. Update the relevant section in this guide
  2. Update DOCUMENTATION_INDEX.md if structure changed
  3. Update CLAUDE.md guidelines if rules changed
  4. Update Last Modified date below

Last Updated: November 17, 2025 Version: 1.0 Maintained By: HeliosDB Documentation Team