Merge pull request #27 from vyos-contrib/feat/architecture-and-quality-improvements

feat: v0.4.0 - Architecture refactor, bug fixes, and quality improvem…

1 files changed, 88 insertions, 0 deletions

diff --git a/docs/concepts.md b/docs/concepts.md
new file mode 100644
index 0000000..058d20c
--- /dev/null
+++ b/docs/concepts.md
@@ -0,0 +1,88 @@
+# Concepts
+
+Key concepts and architecture of PyVyOS.
+
+## Architecture Overview
+
+PyVyOS is built on a REST client architecture:
+- `RestClient`: Base class handling HTTP communication
+- `VyDevice`: High-level interface for VyOS operations
+- `ApiResponse`: Standardized response structure
+
+## API Command Structure
+
+VyOS API uses a hierarchical command structure:
+- Commands: `configure`, `retrieve`, `show`, `generate`, `reset`
+- Operations: `set`, `delete`, `showConfig`, `returnValues`
+- Paths: Array representing configuration hierarchy
+
+## Path Format
+
+Paths are always arrays representing the configuration tree:
+
+```python
+# Single path
+["interfaces", "ethernet", "eth0", "address", "192.168.1.1/24"]
+
+# Multiple paths (for configure_set)
+[
+    ["interfaces", "ethernet", "eth0", "address", "192.168.1.1/24"],
+    ["interfaces", "ethernet", "eth0", "description", "Management"]
+]
+```
+
+## Response Handling
+
+All methods return `ApiResponse`:
+- Consistent error checking
+- Sanitized request payloads (API keys removed)
+- Structured result data
+
+## Operation Types
+
+### Configuration Operations
+- `set`: Add or modify configuration
+- `delete`: Remove configuration
+- `showConfig`: Get full configuration
+- `returnValues`: Get specific values
+
+### Operational Commands
+- `show`: Execute show commands
+- `generate`: Generate configurations/keys
+- `reset`: Reset state/cache
+
+## Multi-Operation Requests
+
+`configure_multiple_op` allows atomic operations:
+- Multiple set/delete operations in one API call
+- Transaction-like behavior
+- Better performance than individual calls
+
+## Error Handling Strategy
+
+PyVyOS uses defensive error handling:
+- Network errors captured as exceptions
+- API errors returned in response.error
+- HTTP status codes in response.status
+
+## Security Considerations
+
+- API keys never appear in response.request
+- SSL verification configurable per connection
+- Timeout protection prevents hanging connections
+
+## Connection Lifecycle
+
+1. Initialize VyDevice with connection parameters
+2. Parameters validated on initialization
+3. Each method creates new HTTP request
+4. Responses parsed and returned as ApiResponse
+
+## Best Practices
+
+- Use environment variables for credentials
+- Enable SSL verification in production
+- Handle errors explicitly
+- Use configure_multiple_op for bulk changes
+- Set appropriate timeouts for operations
+