diff options
Diffstat (limited to 'docs/development/architecture.md')
| -rw-r--r-- | docs/development/architecture.md | 77 |
1 files changed, 77 insertions, 0 deletions
diff --git a/docs/development/architecture.md b/docs/development/architecture.md new file mode 100644 index 0000000..aceda08 --- /dev/null +++ b/docs/development/architecture.md @@ -0,0 +1,77 @@ +# Development Architecture (Proposed) + +## Goals +- Strong separation of concerns (transport, domain, specs, utils) +- Backward compatibility for 0.3.0 via shims +- Clear public API surface and internal boundaries +- Minimal maintenance burden for a public, official SDK + +## Source Layout (file tree) +``` +pyvyos/ + __init__.py # public API exports (VyDevice, ApiResponse) + core/ # internal, stable layers + __init__.py + rest_client.py # RestClient, ApiResponse (transport layer) + device.py # VyDevice (domain layer) + specs/ # optional Pydantic models (validation) + __init__.py + models.py # base models (ApiRequest/Response) + commands/ # split by responsibility + __init__.py + configure.py # set, delete, multiple_op + retrieve.py # show_config, return_values + config_file.py # save, load (path: []) + show.py # show + generate.py # generate + reset.py # reset + system.py # reboot, poweroff + image.py # add, delete + utils/ # reusable helpers (no side effects) + __init__.py + json.py # safe_json, redact_key + http.py # timeouts, retries (future) + paths.py # path builder helpers + ids.py # request_id helpers + exceptions.py # typed exceptions (SDKError, HttpError, ApiError) + types.py # public typing aliases if needed + device.py # shim re-export (compat) + rest.py # shim re-export (compat) + vyos_api/ # JSON specs (docs/reference, optional at runtime) +``` + +## Layers & Responsibilities +- Transport (core.rest_client): HTTP, payload assembly, response validation +- Domain (core.device): high-level methods (configure, show, reset, etc.) +- Specs (specs.*): optional Pydantic models to validate requests/answers +- Utils: pure helpers (formatting, ids, path building) +- Shims (device.py, rest.py): ensure 0.3.0 compatibility + +## Public API Surface +- `from pyvyos import VyDevice, ApiResponse` +- Stable imports; internal moves hidden by shims + +## Compatibility Strategy +- Keep shims until 1.0.0 +- Deprecation policy: warn after N minors, remove at next major +- Document migration path (import from `pyvyos.core` for new code) + +## Data Validation Flow (optional) +- App builds `path` with utils.paths +- If validation enabled, use `specs.commands.*` models +- RestClient serializes payload and executes request +- Response validated (structure: success/data/error) + +## Testing Strategy +- Unit: core.rest_client and core.device isolated via monkeypatch +- Contract: JSON fixtures mirror VyOS responses +- E2E (future): optional with test VyOS VM + +## Packaging +- Include `vyos_api/` only if needed at runtime +- Otherwise treat it as docs/reference, not required by the package + +## Naming & Conventions +- Use underscores `_` in file and module names +- One responsibility per module (keep files small) +- Typed public APIs, specific exceptions, no prints (only logging) |