MidasDocs/PoliciesAndStandards/FilePathStandards.md

File Path Standards

Table of Contents

1. Purpose
2. General Directory Structure
3. Naming Conventions
4. Special Conventions
5. Example Directory Structure
6. Guidelines for Adding New Files

---

Purpose

This document establishes the standards for organizing, naming, and structuring files and directories across all projects within MidasTechnologies. Following these guidelines ensures a clean, predictable file layout, making it easy for team members to navigate, understand, and maintain the repository. Clear structure contributes to project scalability, maintainability, and a smoother development experience.

---

General Directory Structure

The project root directory, MidasTechnologies, includes key folders for code, tests, configuration, documentation, and other resources. The layout below provides an organized structure for optimal project navigation and resource management.

MidasTechnologies/
│
├── src/                   # Source code for the entire project
│   ├── neural-network/    # Neural network-related code
│   ├── data-collection/   # Code and data processing tools for data collection
│   │   ├── tests/         # Contains unit tests, integration tests, and test resources
│   │   └── ...            # Additional data collection code modules
│   ├── sentiment-analysis/ # Sentiment analysis-related code
│   ├── frontend/          # Frontend-related code and assets
│   └── ...                # Additional modules or features as needed
│
├── docs/                  # All project documentation
│   ├── BusinessDocumentation/ # Business-related documentation
│   ├── ManPages/          # Global code documentation
│   └── PoliciesAndStandards/ # Documentation standards, policies, and guidelines
│
├── config/                # Configuration files and environment settings
├── data/                  # Static data files for the entire project
├── scripts/               # Utility and setup scripts (e.g., deployment scripts)
├── examples/              # Examples and sample code for demonstrating project usage
└── assets/                # Static assets (images, icons, etc.) for frontend or docs

---

Naming Conventions

1. File Names

   • All file names should be in lowercase and use underscores to replace spaces (e.g., data_loader.py).
   • Avoid any whitespace, special characters, or symbols. Stick to letters, numbers, and underscores.
   • If a file is specific to a particular module or feature, use a descriptive prefix or suffix to clarify its purpose, such as user_model.py.

2. Directory Names

   • Directory names should be in all lowercase and use hyphens (-) to replace spaces (e.g., user-auth).
   • Avoid whitespace and special characters to maintain consistency.
   • src/ Directories: Organize files by functionality, such as api, models, services, data-collection, and utils.

3. Document Files

   • Documentation should be in Markdown (.md) or Plain Text (.txt) format.
   • Documentation filenames should follow a capitalized naming convention (e.g., README.md or GitAndGithubStandards.md).

4. Environment Variables

   • Use all uppercase with underscores (e.g., DATABASE_URL).

5. Configuration Files

   • Use .yaml or .json for configuration files to maintain readability and consistency.

6. Classes

   • Class names should follow PascalCase (e.g., UserService).

GitHub File Naming and Directory Limitations

When creating or modifying file names and directories, keep in mind GitHub's limitations and best practices:

• Character Limit: File and directory names should not exceed 255 characters.
• Special Characters: Avoid using special characters (e.g., @, !, $, %) as they may cause compatibility issues across different operating systems.
• Case Sensitivity: GitHub is case-sensitive, so FilePathStandards.md and filepathstandards.md are treated as distinct files. Use consistent lowercase naming for all files as per our standards.
• Path Depth: Aim to keep directory nesting shallow to improve readability and reduce navigation complexity.

Adhering to these guidelines will ensure compatibility across different development environments and maintain uniformity within the repository.

---

Special Conventions

1. Documentation Directories

   • Documentation directories in docs/ are an exception to general naming conventions. Documentation files use Capitalized Names (e.g., ManPages, BusinessDocumentation).

2. README Files

   • Each root module in the project should contain its own README file, which provides context and instructions for the specific module.
   • The README file must be in Markdown (README.md), Plain Text (README.txt), or have no extension (simply README).
   • Global documentation for the entire project is held in the docs/ManPages directory.

3. Test Directories

   • All root modules should contain a tests directory, located one level deep within the main module folder (e.g., src/data-collection/tests). This folder will house unit tests, integration tests, and other test resources relevant to the module.

4. Data Directories

   • A data/ directory in the project root holds static data files used across the entire project.
   • If a data/ directory exists within a src module, it may have specific functionality. Refer to the module’s README file for further clarification.

---

Example Directory Structure

MidasTechnologies/
│
├── src/
│   ├── neural-network/
│   │   ├── models.py          # Neural network models
│   │   ├── training_script.py # Training scripts
│   │   └── ...
│   │
│   ├── data-collection/
│   │   ├── data_sources.py    # Sources for data collection
│   │   ├── process_data.py    # Data processing scripts
│   │   ├── tests/             # Contains unit tests, integration tests, and test resources
│   │   └── ...
│   │
│   ├── sentiment-analysis/
│   │   ├── analyze_sentiment.py # Sentiment analysis script
│   │   └── ...
│   │
│   ├── frontend/
│   │   ├── app.js             # Frontend application code
│   │   └── ...
│   │
│   └── ...
│
├── docs/
│   ├── README.md              # Project overview documentation
│   ├── BusinessDocumentation/ # Legal and business-related documentation
│   ├── ManPages/              # Global code documentation
│   └── PoliciesAndStandards/  # Markdown files on standards, policies, and guidelines
│
├── config/
│   ├── config.yaml            # Main project configuration file
│   └── dev_config.yaml        # Development-specific configuration
│
├── data/
│   └── sample_data.csv        # Static data file example
│
├── scripts/
│   ├── setup.sh               # Script to initialize the project setup
│   └── deploy.sh              # Deployment script
│
├── examples/
│   ├── usage_example.py       # Example usage of main project features
│   └── ...
│
└── assets/
    ├── logo.png               # Project logo
    └── favicon.ico            # Icon for frontend

---

Guidelines for Adding New Files

1. Check the Existing Structure

   • Review the current directory structure before adding a new file to ensure you place it in the most relevant folder.
   • Avoid creating redundant or deeply nested directories without a strong rationale.

2. Follow Naming Conventions

   • Ensure that all files and directories follow the naming conventions specified above, keeping the structure consistent and predictable.

3. Document New Directories

   • When adding a new folder that doesn’t fit existing patterns, include a README.md file or entry in the main project documentation within docs/ to explain its purpose.

4. Requirements for Documentation

   • All documentation files should be placed in the appropriate subdirectory within docs/.
   • Markdown or text files should be used for documentation purposes, avoiding other file formats where possible.