slopdocs/structure.slopdocs.filesystem.md

Slopdocs Filesystem Structure

Base Directory Structure

Location

All slopdocs content is stored in the standardized base directory:

/usr/share/slopdocs

This centralized location ensures:

• Consistent access across different systems and environments
• Easy integration with automated tools and scripts
• Standardized path resolution for LLM systems
• Simple backup and version control procedures
• Efficient resource utilization through unified access patterns

Flat File Structure

Slopdocs uses a flat filesystem structure with no subdirectories. All documentation files are stored directly in the base directory. The organizational hierarchy is achieved through the dot-separated naming convention rather than physical directory structure.

This approach minimizes computational overhead by:

• Eliminating complex directory traversal operations
• Reducing path resolution complexity
• Simplifying file discovery for automated systems

• Optimizing for efficient machine processing

  /usr/share/slopdocs/
  ├── library.react.frontend.md
  ├── library.express.backend.md
  ├── library.postgresql.database.md
  ├── utilities.git.system.md
  ├── utilities.docker.build.md
  ├── utilities.kubernetes.deploy.md
  ├── stack.node.versions.md
  ├── stack.npm.dependencies.md
  ├── stack.python.compatibility.md
  ├── structure.microservices.architecture.md
  ├── structure.repository.patterns.md
  ├── structure.naming.guidelines.md
  ├── ethics.ai.responsible.md
  ├── ethics.code.quality.md
  └── ethics.collaboration.guidelines.md
  

Dot-Separated Naming Scheme

Format

The naming convention follows a hierarchical dot-separated format:

root.component.md
root.component.subcomponent.md
root.component.subcomponent.subsubcomponent.md

Naming Components

• root: One of the five primary categories (library, utilities, stack, structure, ethics)
• component: The specific component, technology, or domain being documented
• subcomponent (optional): Further subdivision of the component
• additional levels (optional): As many levels as needed for proper organization
• extension: Always .md for markdown format

Namespace Requirements

• Minimum: 2 namespace parts (root.component.md)
• Maximum: Unlimited parts as needed for proper organization
• Guideline: Use as many namespace parts as needed to create logical, well-organized documentation structure

Naming Convention Rules

• All components are lowercase
• Multi-word components use hyphens for separation
• Each dot represents a level in the logical hierarchy (nesting)
• The file extension is always .md
• Focus on practical, descriptive names that clearly indicate content
• Use dots to create logical nesting structure (e.g., library.json-glib.parsing.md)

Examples of Valid File Names

Minimal Namespace Examples (2 parts)

library.react.md
utilities.docker.md
stack.node.md
structure.microservices.md
ethics.responsible.md

Standard Namespace Examples (3 parts)

library.react.frontend.md
utilities.docker.build.md
stack.node.versions.md
structure.microservices.architecture.md
ethics.ai.responsible.md

Complex Namespace Examples (4+ parts)

library.react.frontend.components.md
utilities.docker.build.multi-stage.md
stack.node.v18.versions.md
structure.microservices.communication.patterns.md
ethics.ai.responsible.deployment.md

Root Namespaces

library

Purpose: Documentation for software libraries, frameworks, and APIs

Scope:

• External libraries and frameworks
• Internal shared libraries
• API documentation
• SDK documentation
• Package management libraries

Examples:

• library.react.frontend.md - React frontend library documentation
• library.express.backend.md - Express.js backend framework
• library.postgresql.database.md - PostgreSQL database library
• library.libinvercargill.core.md - Custom internal library core documentation

utilities

Purpose: System utilities, command-line tools, and helper applications

Scope:

• System administration tools
• Command-line interfaces
• Development utilities
• Build and deployment tools
• Monitoring and debugging utilities

Examples:

• utilities.git.system.md - Git version control system
• utilities.docker.build.md - Docker containerization tool
• utilities.kubernetes.deploy.md - Kubernetes deployment system
• utilities.prometheus.monitor.md - Prometheus monitoring system

stack

Purpose: Technology stack information, including version compatibility and dependencies

Scope:

• Technology stack definitions
• Version compatibility matrices
• Dependency management
• Environment specifications
• Platform requirements

Examples:

• stack.node.versions.md - Node.js version specifications
• stack.npm.dependencies.md - NPM package dependencies
• stack.python.compatibility.md - Python compatibility information
• stack.production.requirements.md - Production environment requirements

structure

Purpose: System architecture, design patterns, and organizational guidelines

Scope:

• System architecture documentation
• Design patterns and principles
• Project structure guidelines
• Code organization standards
• Development workflows

Examples:

• structure.microservices.architecture.md - Microservices architecture
• structure.repository.patterns.md - Repository pattern implementation
• structure.naming.guidelines.md - Naming conventions
• structure.development.workflows.md - Development workflow processes

ethics

Purpose: Development ethics, best practices, and responsible AI guidelines

Scope:

• Ethical development principles
• Responsible AI guidelines
• Code of conduct
• Accessibility standards
• Security and privacy considerations

Examples:

• ethics.ai.responsible.md - Responsible AI development
• ethics.code.quality.md - Code quality standards
• ethics.collaboration.guidelines.md - Team collaboration principles
• ethics.accessibility.standards.md - Accessibility requirements

File Naming Best Practices

Lowercase Usage

Always use lowercase letters for all components in the filename:

✓ library.react.frontend.md
✗ Library.React.Frontend.md
✗ library.REACT.frontend.md

Hyphen Separation

Use hyphens to separate multi-word components:

✓ utilities.kubernetes.deploy.md
✗ utilities.kubernetesdeployment.md
✓ structure.naming.guidelines.md
✗ structure.namingguidelines.md

Version Handling

Include version information when relevant:

✓ library.react.v18.frontend.md
✓ stack.node.v18.versions.md
✓ utilities.docker.v24.build.md

Avoiding Naming Conflicts

Be specific to avoid conflicts:

✓ library.react.frontend.md
✓ library.react.native.md
✗ library.react.md (too generic)

Component Specificity

Use specific component names rather than generic ones:

✓ library.postgresql.database.md
✗ library.postgresql.md
✓ utilities.git.system.md
✗ utilities.git.md

Resource-Efficient Naming

Choose names that balance clarity with brevity to minimize processing overhead:

✓ library.react.md (minimal, clear)
✓ library.react.frontend.md (specific when needed)
✓ library.react.frontend.component-library.md (as specific as needed)
✓ library.react.frontend.component-library.ui-elements.md (as specific as needed)
✓ library.react.frontend.component-library.ui-elements.buttons.md (as specific as needed)
✓ library.json-glib.parsing.md (correct - dots create nesting)
✗ library.json.glib.parsing.md (incorrect - breaks logical hierarchy)

Document Size Management

Break large documentation into smaller, focused files when:

• A single document becomes excessively long (over 2000 words)
• Different sections serve distinct purposes
• Content can be logically separated into standalone topics
• Specific information is frequently accessed independently

Example of breaking down large documentation:

Instead of: library.react.frontend.everything.md (very large)

Use:
- library.react.frontend.md (core concepts)
- library.react.frontend.components.md (component patterns)
- library.react.frontend.hooks.md (custom hooks)
- library.react.frontend.routing.md (navigation)
- library.react.frontend.state-management.md (state patterns)
- library.react.frontend.testing.md (testing approaches)

File Organization Examples

Minimal Documentation Files (2-part namespaces)

For straightforward documentation with a single focus:

library.react.md
utilities.git.md
stack.node.md
ethics.responsible.md

Standard Documentation Files (3-part namespaces)

For more specific documentation:

library.react.frontend.md
utilities.git.system.md
stack.node.versions.md
ethics.responsible.ai.md

Complex Documentation with Multiple Components

For comprehensive documentation covering multiple aspects:

library.react.frontend.md
library.react.components.md
library.react.hooks.md
library.react.routing.md

utilities.docker.build.md
utilities.docker.deploy.md
utilities.docker.networking.md
utilities.docker.volumes.md

Version-Specific Documentation

For documenting different versions of the same technology:

library.react.v17.frontend.md
library.react.v18.frontend.md
library.react.v19.frontend.md

stack.node.v16.versions.md
stack.node.v18.versions.md
stack.node.v20.versions.md

Cross-References Between Files

Organize related documentation to enable easy cross-referencing:

structure.microservices.architecture.md
structure.microservices.communication.md
structure.microservices.deployment.md
structure.microservices.monitoring.md

utilities.kubernetes.deploy.md
utilities.kubernetes.services.md
utilities.kubernetes.configmaps.md
utilities.kubernetes.secrets.md

LLM Interaction with Filesystem

Locating Relevant Documentation

LLMs should follow this process to find relevant documentation:

1. Parse the Query: Identify keywords and intent from the user's request
2. Map to Namespace: Determine which root namespace is most relevant
3. Filter by Component: Match specific components within the namespace
4. Consider Subcomponents: Look for more specific subcomponent documentation if needed
5. Optimize for Efficiency: Prioritize minimal namespace matches first

Example process:

Query: "How do I deploy React applications with Docker?"
1. Keywords: React, deploy, Docker
2. Namespaces: library (React), utilities (Docker)
3. Components: frontend, build, deploy
4. Candidate files: library.react.md, library.react.frontend.md, utilities.docker.md, utilities.docker.build.md, utilities.docker.deploy.md
5. Priority order: library.react.md → library.react.frontend.md → utilities.docker.md → utilities.docker.deploy.md

Interpreting File Names

LLMs should parse file names hierarchically:

library.react.frontend.md
└── root: library (software library documentation)
    └── component: react (React library)
        └── subcomponent: frontend (frontend-specific aspects)

library.react.md
└── root: library (software library documentation)
    └── component: react (React library - minimal namespace)

utilities.docker.deploy.md
└── root: utilities (system utilities)
    └── component: docker (Docker tool)
        └── subcomponent: deploy (deployment functionality)

Handling Missing or Outdated Files

When documentation is missing or outdated:

1. Check for Alternatives: Look for related documentation in the same namespace
2. Check Version-Specific Files: Look for version-specific documentation if applicable
3. Check General Documentation: Fall back to more general documentation
4. Identify Gaps: Note missing documentation for future creation

Example fallback process:

Looking for: library.react.v19.frontend.md
1. Check: library.react.v19.frontend.md (not found)
2. Check: library.react.frontend.md (found - use as fallback)
3. Check: library.react.v18.frontend.md (found - use for version comparison)
4. Note: Create library.react.v19.frontend.md when possible

Content Discovery Strategy

LLMs should use this strategy for efficient content discovery:

1. Keyword Matching: Match query keywords with document content
2. Cross-Reference Following: Follow links to related documents
3. Context Building: Build context from multiple related documents
4. Resource Optimization: Prioritize minimal namespace files to reduce processing overhead

Query Resolution Workflow

For answering technical questions:

1. Parse query to identify relevant namespaces
2. Locate candidate documents based on filename patterns
3. Extract specific information from documents
4. Synthesize information from multiple documents when needed
5. Include references to source documents

Integration with Development Workflows

LLMs should integrate slopdocs knowledge into development workflows:

1. Code Generation: Use slopdocs to inform code generation
2. Tool Selection: Reference utility documentation for tool selection
3. Architecture Decisions: Consult structure documentation for patterns
4. Version Compatibility: Check stack documentation for compatibility
5. Best Practices: Apply ethics guidelines to development decisions
6. Resource Efficiency: Choose minimal namespace documentation when sufficient

---

This document defines the slopdocs filesystem structure, including the standardized base directory, flat file organization, and dot-separated naming convention. It provides detailed guidelines for organizing documentation across five primary namespaces (library, utilities, stack, structure, and ethics) with examples of valid naming patterns. The document serves as a comprehensive reference for LLMs to efficiently locate, interpret, and navigate slopdocs content while optimizing for resource efficiency.

This filesystem structure documentation serves as a technical reference for LLMs to understand and navigate the slopdocs filesystem structure effectively while maintaining ethical principles of truth, responsibility, low resource usage, and practical problem solving.