43b2e44d95
- Created `project-structure.md` to outline the directory layout, crate dependencies, design principles, module guidelines, and naming conventions for the NxMesh codebase. - Introduced `roadmap.md` detailing the development phases, milestones, tasks, deliverables, and resource requirements for the NxMesh project, spanning from foundational setup to enterprise features.
105 lines
3.1 KiB
Markdown
105 lines
3.1 KiB
Markdown
# 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.
|