# NxMesh - Agent Instructions

This document provides context for AI agents working on the NxMesh project.

## Project Overview

**NxMesh** is a distributed nginx management system using a master-agent architecture:

- **Master (Control Plane)**: Central API, embedded Web UI, configuration distribution, cluster management
- **Agent (Data Plane)**: Sidecar that manages local nginx instances
- **Web UI**: Vite React-based admin console, embedded and served by master

## Quick Links to Documentation

| Document | Purpose |
|----------|---------|
| [README.md](./README.md) | Project overview and quick start |
| [docs/architecture.md](./docs/architecture.md) | System design and data flow |
| [docs/features.md](./docs/features.md) | Detailed feature specifications |
| [docs/roadmap.md](./docs/roadmap.md) | Development phases and milestones |
| [docs/api.md](./docs/api.md) | REST and gRPC API specifications |

| [docs/project-structure.md](./docs/project-structure.md) | Code organization |

## Technology Stack

| Component | Technology |
|-----------|------------|
| Backend | Rust (Axum, Tonic, SeaORM) |
| Frontend | React + TypeScript + Vite |
| Database | PostgreSQL 16+ |
| Cache | Redis |
| Message Format | Protocol Buffers (gRPC) |
| Container | Docker |
| Orchestration | Kubernetes (optional) |

## Development Environment

This project uses Dev Containers for consistent development:

```bash
# All dependencies are pre-installed in the devcontainer
just setup    # Initial setup
just dev      # Start development
```

### Pre-configured Services

The devcontainer includes:
- PostgreSQL database
- Redis cache
- Nginx instance
- Rust toolchain
- Node.js/Bun for frontend

## Key Design Decisions

1. **Master-Agent Protocol**: Bidirectional gRPC streaming for real-time communication
2. **Configuration Management**: Template-based (Handlebars) with versioning
3. **Security**: TLS + Shared Secret for agent connections, JWT for API auth
4. **Deployment**: Support for Docker sidecar, K8s sidecar, and standalone modes

## Common Tasks

### Adding a New API Endpoint

1. Define route in `crates/nxmesh-master/src/api/v1/`
2. Add request/response types to shared models
3. Implement handler with proper error handling
4. Add tests
5. Update OpenAPI documentation

### Adding a Database Entity

1. Create migration with `sea-orm-cli migrate generate <name>`
2. Define entity in `crates/nxmesh-master/src/db/entities/`
3. Add repository in `crates/nxmesh-master/src/db/repositories/`
4. Update service layer

### Adding Agent Functionality

1. Add module in `crates/nxmesh-agent/src/`
2. Update gRPC protocol if needed (`crates/nxmesh-proto/proto/`)
3. Implement handler in agent
4. Add corresponding master service

## Testing

```bash
just test              # All tests
just test-unit         # Unit tests only
just test-integration  # Integration tests
```

## Code Style

- Follow Rust API Guidelines
- Use `cargo fmt` and `cargo clippy`
- All public APIs must have doc comments
- Error types should be descriptive and actionable

## Questions?

Refer to the documentation in `docs/` directory or ask the team.