nself Directory Structure Guide

Overview

This document outlines the directory structure for nself v0.3.9, designed for maintainability, modularity, and clear separation of concerns.

Root Directory Structure

nself/
├── README.md                    # Project overview and quick start
├── CHANGELOG.md                 # Version history and release notes
├── LICENSE                      # MIT License
├── install.sh                   # Installation script for system-wide setup
├── .gitignore                   # Git ignore patterns
├── bin/                         # Executable entry points
├── src/                         # Source code and implementation
└── docs/                        # Documentation and guides

Source Code Organization (`src/`)

Core Structure

src/
├── VERSION                      # Current version (v0.3.9)
├── cli/                         # Command-line interface implementations
├── lib/                         # Shared libraries and utilities
├── services/                    # Service management modules
├── templates/                   # Configuration and Docker templates
└── tools/                       # Development and maintenance tools

CLI Commands (`src/cli/`)

All command implementations following consistent patterns:

cli/
├── nself.sh                     # Main CLI dispatcher and router
├── help.sh                      # Help system and documentation
├── init.sh                      # Project initialization
├── build.sh                     # Infrastructure generation
├── start.sh                     # Service startup management
├── stop.sh                      # Service shutdown management
├── restart.sh                   # Service restart management
├── status.sh                    # Service status monitoring
├── logs.sh                      # Log viewing and management
├── doctor.sh                    # System diagnostics
├── backup.sh                    # Backup and restore operations
├── db.sh                        # Database operations
├── email.sh                     # Email service configuration
├── ssl.sh                       # SSL certificate management
├── urls.sh                      # Service URL display
├── prod.sh                      # Production configuration
├── trust.sh                     # SSL certificate installation
├── validate.sh                  # Configuration validation
├── exec.sh                      # Container command execution
├── scale.sh                     # Resource scaling management
├── metrics.sh                   # Metrics and monitoring
├── clean.sh                     # Docker cleanup operations
├── diff.sh                      # Configuration difference analysis
├── reset.sh                     # Project reset operations
├── rollback.sh                  # Version rollback management
├── monitor.sh                   # Real-time monitoring
├── scaffold.sh                  # Service scaffolding
├── update.sh                    # nself version updates
├── version.sh                   # Version information
├── admin.sh                     # Admin UI management (v0.3.9)
├── search.sh                    # Search service management (v0.3.9)
├── deploy.sh                    # VPS deployment (v0.3.9)
└── wizard/                      # Interactive setup wizard (v0.3.9)
    ├── init-wizard.sh           # Main wizard controller
    ├── detection.sh             # Project framework detection
    ├── prompts.sh               # Interactive UI components
    └── templates.sh             # Project template definitions

Shared Libraries (`src/lib/`)

Reusable functionality organized by purpose:

lib/
├── utils/                       # Common utilities
│   ├── display.sh               # Output formatting and colors
│   ├── env.sh                   # Environment file handling
│   ├── docker.sh                # Docker operations
│   ├── network.sh               # Network utilities
│   └── validation.sh            # Input validation helpers
├── config/                      # Configuration management
│   ├── constants.sh             # System constants
│   ├── smart-defaults.sh        # Intelligent default values
│   └── validation.sh            # Configuration validation
├── hooks/                       # Command lifecycle hooks
│   ├── pre-command.sh           # Pre-execution hooks
│   └── post-command.sh          # Post-execution hooks
├── ssl/                         # SSL certificate management
│   ├── auto-ssl.sh              # Automatic SSL generation
│   └── auto-renew.sh            # Certificate renewal
├── monitoring/                  # System monitoring
│   ├── health.sh                # Health check utilities
│   ├── metrics.sh               # Metrics collection
│   └── alerts.sh                # Alert management
├── backup/                      # Backup operations
│   ├── core.sh                  # Core backup functionality
│   └── s3.sh                    # S3 integration
├── deployment/                  # Deployment utilities
│   ├── ssh.sh                   # SSH deployment helpers
│   └── validation.sh            # Deployment validation
└── wizard/                      # Wizard system (v0.3.9)
    └── environment-manager.sh   # Multi-environment management

Service Management (`src/services/`)

Service-specific logic and configurations:

services/
├── postgres/                    # PostgreSQL management
├── redis/                       # Redis configuration
├── minio/                       # MinIO object storage
├── hasura/                      # Hasura GraphQL engine
├── auth/                        # Authentication service
├── nginx/                       # Nginx reverse proxy
├── docker/                      # Docker Compose generation
└── monitoring/                  # Monitoring stack

Templates (`src/templates/`)

Configuration templates and examples:

templates/
├── .env.example                 # Complete environment reference
├── docker-compose/              # Docker Compose templates
├── nginx/                       # Nginx configuration templates
├── ssl/                         # SSL certificate templates
└── certs/                       # Pre-generated certificates
    ├── localhost/               # Local development certificates
    └── nself-org/               # nself.org domain certificates

Documentation (`docs/`)

Comprehensive documentation for users and developers:

docs/
├── COMMANDS.md                  # Complete command reference
├── v0.3.9.md                    # v0.3.9 release notes
├── ARCHITECTURE.MD              # System architecture overview
├── ENVIRONMENT_CONFIGURATION.MD # Environment setup guide
├── TROUBLESHOOTING.MD           # Common issues and solutions
├── API.MD                       # API documentation
├── CHANGELOG.MD                 # Version history
├── ROADMAP.md                   # Future development plans
├── CONTRIBUTING.MD              # Contribution guidelines
├── RELEASES.MD                  # Release information
├── EXAMPLES.MD                  # Usage examples
└── README.MD                    # Getting started guide

Executable Entry Points (`bin/`)

Simple wrappers for system-wide installation:

bin/
├── nself                        # Main nself command wrapper
├── urls                         # Direct URL display
└── [other-commands]             # Additional command aliases

Design Principles

Modularity

Each command is self-contained in its own file
Shared functionality is centralized in lib/
Clear separation between CLI, logic, and templates

Consistency

All commands follow the same structure and patterns
Consistent naming conventions throughout
Standardized help and error handling

Extensibility

New commands can be added easily in src/cli/
Service modules are pluggable and independent
Template system supports customization

Maintainability

Clear file organization by functionality
Documented interfaces between modules
Comprehensive testing structure

Backward Compatibility

Existing command structure preserved
New v0.3.9 features are additive
Legacy functionality remains unchanged

File Naming Conventions

Commands: command-name.sh (kebab-case with .sh extension)
Libraries: module-name.sh (descriptive, organized by directory)
Templates: template-name.ext (matches target file extension)
Documentation: TOPIC.MD (uppercase .MD for main docs, lowercase .md for version-specific)

Execution Flow

Entry Point: bin/nself → src/cli/nself.sh
Command Routing: nself.sh identifies and sources appropriate command file
Library Loading: Commands source required libraries from src/lib/
Template Processing: Commands use templates from src/templates/
Service Integration: Commands interact with services via src/services/

This structure supports nself's evolution from a simple CLI tool to a comprehensive backend platform while maintaining clarity and ease of development.

DIRECTORY_STRUCTURE - nself-org/cli GitHub Wiki

nself Directory Structure Guide

Overview

Root Directory Structure

Source Code Organization (`src/`)

Core Structure

CLI Commands (`src/cli/`)

Shared Libraries (`src/lib/`)

Service Management (`src/services/`)

Templates (`src/templates/`)

Documentation (`docs/`)

Executable Entry Points (`bin/`)

Design Principles

Modularity

Consistency

Extensibility

Maintainability

Backward Compatibility

File Naming Conventions

Execution Flow

⚠️ GitHub.com Fallback ⚠️

DIRECTORY_STRUCTURE - nself-org/cli GitHub Wiki

nself Directory Structure Guide

Overview

Root Directory Structure

Source Code Organization (src/)

Core Structure

CLI Commands (src/cli/)

Shared Libraries (src/lib/)

Service Management (src/services/)

Templates (src/templates/)

Documentation (docs/)

Executable Entry Points (bin/)

Design Principles

Modularity

Consistency

Extensibility

Maintainability

Backward Compatibility

File Naming Conventions

Execution Flow

⚠️ **GitHub.com Fallback** ⚠️

Source Code Organization (`src/`)

CLI Commands (`src/cli/`)

Shared Libraries (`src/lib/`)

Service Management (`src/services/`)

Templates (`src/templates/`)

Documentation (`docs/`)

Executable Entry Points (`bin/`)

⚠️ GitHub.com Fallback ⚠️