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