NxMesh-old/docs/project-structure.md

NxMesh Project Structure

This document outlines the recommended project structure for the NxMesh codebase.

Directory Layout

nxmesh/
├── Cargo.toml                    # Workspace root
├── Cargo.lock
├── README.md
├── LICENSE
├── justfile                      # Task runner
├── AGENTS.md                     # AI agent context
├──
├── crates/                       # Rust workspace crates
│   ├── nxmesh-core/             # Shared core library
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── lib.rs
│   │       ├── models/          # Shared data models
│   │       │   ├── mod.rs
│   │       │   ├── organization.rs
│   │       │   ├── workspace.rs
│   │       │   ├── agent.rs
│   │       │   ├── config.rs
│   │       │   └── certificate.rs
│   │       ├── crypto/          # Encryption, hashing
│   │       ├── validation/      # Input validation
│   │       └── error.rs         # Common error types
│   │
│   ├── nxmesh-proto/            # Protocol buffers
│   │   ├── Cargo.toml
│   │   ├── build.rs
│   │   └── proto/
│   │       ├── agent.proto
│   │       ├── config.proto
│   │       └── common.proto
│   │
│   ├── nxmesh-master/           # Control plane
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── main.rs
│   │       ├── lib.rs
│   │       ├── api/             # REST API handlers
│   │       │   ├── mod.rs
│   │       │   ├── routes.rs
│   │       │   ├── middleware/
│   │       │   ├── v1/          # API version 1
│   │       │   │   ├── mod.rs
│   │       │   │   ├── organizations.rs
│   │       │   │   ├── workspaces.rs
│   │       │   │   ├── agents.rs
│   │       │   │   ├── virtual_hosts.rs
│   │       │   │   ├── upstreams.rs
│   │       │   │   ├── certificates.rs
│   │       │   │   └── metrics.rs
│   │       │   └── websocket.rs
│   │       ├── grpc/            # gRPC service
│   │       │   ├── mod.rs
│   │       │   ├── server.rs
│   │       │   ├── agent_service.rs
│   │       │   └── interceptor.rs
│   │       ├── config/          # Configuration
│   │       │   ├── mod.rs
│   │       │   └── settings.rs
│   │       ├── db/              # Database layer
│   │       │   ├── mod.rs
│   │       │   ├── connection.rs
│   │       │   ├── migration.rs
│   │       │   └── repositories/
│   │       ├── services/        # Business logic
│   │       │   ├── mod.rs
│   │       │   ├── organization_service.rs
│   │       │   ├── workspace_service.rs
│   │       │   ├── agent_service.rs
│   │       │   ├── config_service.rs
│   │       │   ├── certificate_service.rs
│   │       │   └── auth_service.rs
│   │       ├── domain/          # Domain entities
│   │       │   ├── mod.rs
│   │       │   ├── organization.rs
│   │       │   ├── agent.rs
│   │       │   └── config.rs
│   │       ├── infrastructure/  # External integrations
│   │       │   ├── mod.rs
│   │       │   ├── acme/        # Let's Encrypt
│   │       │   ├── storage/     # Object storage
│   │       │   └── notifier/    # Notifications
│   │       ├── events/          # Event bus
│   │       │   ├── mod.rs
│   │       │   ├── bus.rs
│   │       │   └── handlers.rs
│   │       └── cli.rs           # CLI commands
│   │
│   ├── nxmesh-agent/            # Data plane
│   │   ├── Cargo.toml
│   │   └── src/
│   │       ├── main.rs
│   │       ├── lib.rs
│   │       ├── config/          # Agent configuration
│   │       │   ├── mod.rs
│   │       │   └── settings.rs
│   │       ├── master/          # Master communication
│   │       │   ├── mod.rs
│   │       │   ├── client.rs
│   │       │   ├── reconnect.rs
│   │       │   └── stream.rs
│   │       ├── nginx/           # Nginx management
│   │       │   ├── mod.rs
│   │       │   ├── controller.rs
│   │       │   ├── config_manager.rs  # Symlink-based atomic deployment
│   │       │   ├── config_renderer.rs
│   │       │   ├── validator.rs
│   │       │   ├── docker_sidecar.rs  # Docker sidecar (PID namespace sharing)
│   │       │   ├── systemd.rs   # Standalone mode
│   │       │   └── parser.rs    # Nginx config parser
│   │       ├── health/          # Health monitoring
│   │       │   ├── mod.rs
│   │       │   ├── monitor.rs
│   │       │   ├── nginx.rs
│   │       │   └── system.rs
│   │       ├── metrics/         # Metrics collection
│   │       │   ├── mod.rs
│   │       │   ├── collector.rs
│   │       │   └── exporter.rs
│   │       ├── cache/           # Local caching
│   │       │   ├── mod.rs
│   │       │   └── config_cache.rs
│   │       ├── watch/           # File watchers
│   │       │   ├── mod.rs
│   │       │   └── config_watch.rs
│   │       └── cli.rs           # CLI commands
│   │
│   └── nxmesh-cli/              # CLI tool
│       ├── Cargo.toml
│       └── src/
│           ├── main.rs
│           ├── commands/        # CLI commands
│           │   ├── mod.rs
│           │   ├── login.rs
│           │   ├── agent.rs
│           │   ├── config.rs
│           │   └── deploy.rs
│           └── api/             # API client
│
├── frontend/                    # Web UI (embedded in master)
│   ├── package.json
│   ├── vite.config.ts
│   ├── tsconfig.json
│   ├── index.html
│   ├── src/
│   │   ├── main.tsx
│   │   ├── App.tsx
│   │   ├── components/          # Reusable components
│   │   │   ├── common/
│   │   │   ├── layout/
│   │   │   └── forms/
│   │   ├── pages/               # Page components
│   │   │   ├── Dashboard/
│   │   │   ├── Agents/
│   │   │   ├── Configurations/
│   │   │   ├── Certificates/
│   │   │   └── Settings/
│   │   ├── hooks/               # React hooks
│   │   ├── stores/              # State management (Zustand)
│   │   ├── api/                 # API client
│   │   ├── types/               # TypeScript types
│   │   ├── utils/               # Utilities
│   │   └── styles/              # CSS/Tailwind
│   └── public/
│
│   # Build output (dist/) is embedded into master binary
│   # Master serves static files at root path ("/")
│
├── migration/                  # Database migrations
│   ├── Cargo.toml
│   └── src/
│
├── tests/                       # Integration tests
│   ├── integration/
│   │   ├── master_api_tests.rs
│   │   ├── agent_master_tests.rs
│   │   └── config_flow_tests.rs
│   └── fixtures/
│
├── scripts/                     # Build/utility scripts
│   ├── build.sh
│   ├── test.sh
│   └── release.sh
│
├── deploy/                      # Deployment configs
│   ├── docker/
│   │   ├── master.Dockerfile
│   │   ├── agent.Dockerfile
│   │   └── docker-compose.yml
│   ├── k8s/
│   │   ├── namespace.yaml
│   │   ├── master/
│   │   ├── agent/
│   │   └── helm/
│   └── terraform/
│
├── docs/                        # Documentation
│   ├── architecture.md
│   ├── features.md
│   ├── roadmap.md
│   ├── api.md
│   ├── deployment.md
│   └── project-structure.md
│
└── .devcontainer/               # Dev container
    ├── devcontainer.json
    ├── docker-compose.yml
    ├── Dockerfile
    └── nginx/

Crate Dependencies

graph TB
    subgraph "Workspace Crates"
        CLI[nxmesh-cli]
        AGENT[nxmesh-agent]
        MASTER[nxmesh-master]
        PROTO[nxmesh-proto]
        CORE[nxmesh-core]
    end

    CORE --> PROTO
    AGENT --> CORE
    AGENT --> PROTO
    MASTER --> CORE
    MASTER --> PROTO
    CLI --> CORE

Key Design Principles

1. Separation of Concerns

• nxmesh-core: Only shared types and utilities
• nxmesh-master: Only control plane logic
• nxmesh-agent: Only data plane logic
• frontend: Only UI logic

2. Domain-Driven Design (in Master)

domain/          # Domain entities (pure logic)
services/        # Application services (orchestration)
repositories/    # Data access abstraction
api/             # Interface adapters (HTTP, gRPC)
infrastructure/  # External concerns

3. Agent Modularity

Each major concern in the agent is a separate module:

• nginx/: All nginx-specific code
• master/: All master communication code
• health/: All health monitoring code
• metrics/: All metrics code

4. Configuration Management

Use hierarchical config:

1. Default values (in code)
2. Config file (/etc/nxmesh/*.toml)
3. Environment variables
4. Command-line arguments (highest priority)

Module Guidelines

API Versioning

• Always version REST APIs: /api/v1/...
• Maintain backward compatibility within major versions
• Use feature flags for gradual rollouts

Error Handling

• Use thiserror for error definitions
• Propagate errors with context
• Convert to user-friendly messages at API boundary

Testing Structure

// In each module
#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_feature() {
        // unit tests
    }
}

• Unit tests: In same file as code
• Integration tests: In tests/ directory
• E2E tests: Separate crate or external repo

Documentation

• All public APIs must have doc comments
• Include examples in doc comments
• Keep README files in each crate

Build Configuration

Workspace Cargo.toml

[workspace]
members = [
    "crates/nxmesh-core",
    "crates/nxmesh-proto",
    "crates/nxmesh-master",
    "crates/nxmesh-agent",
    "crates/nxmesh-cli",
]
resolver = "3"

[workspace.dependencies]
# Core dependencies
tokio = { version = "1", features = ["full"] }
serde = { version = "1", features = ["derive"] }
thiserror = "1"
tracing = "0.1"

# Web framework
axum = "0.7"
tower = "0.4"
tower-http = "0.5"

# gRPC
tonic = "0.11"
prost = "0.12"

# Database
sea-orm = "2.0.0-rc"
sea-orm-migration = "2.0.0-rc"

# Async
async-trait = "0.1"
futures = "0.3"

# Serialization
serde_json = "1"
toml = "0.8"

# HTTP
reqwest = { version = "0.12", default-features = false }

# Crypto
sha2 = "0.10"
hex = "0.4"

# Testing
tokio-test = "0.4"
mockall = "0.12"

Naming Conventions

Files

• Use snake_case for file names
• Module entry point: mod.rs or {module_name}.rs

Types

• Structs/Enums: PascalCase
• Traits: PascalCase (often ending in able or with verb prefix)
• Functions/Methods: snake_case
• Constants: SCREAMING_SNAKE_CASE
• Generic parameters: Single uppercase letter (T, K, V)

Error Types

• Suffix with Error: ConfigError, AgentError
• Group in error.rs or errors/ module

Feature Flags

• Use kebab-case: postgres-native, tls-rustls

CI/CD Structure

# .github/workflows/
├── ci.yml           # PR checks
├── test.yml         # Test suite
├── release.yml      # Release builds
├── docker.yml       # Docker image builds
└── docs.yml         # Documentation deploy

Scripts

Common operations should have just commands:

# Development
just dev          # Start all services
just dev-backend  # Start backend only
just dev-frontend # Start frontend only

# Testing
just test         # Run all tests
just test-unit    # Unit tests only
just test-integration  # Integration tests

# Building
just build        # Build all
just build-master # Build master only
just build-agent  # Build agent only

# Database
just db-migrate   # Run migrations
just db-reset     # Reset database
just db-console   # Open psql

# Deployment
just docker-build # Build Docker images
just k8s-deploy   # Deploy to Kubernetes