chore(repository): initialize project foundation

2026-08-06 15:20:24 +02:00
commit 62bc8eb00c
6 changed files with 565 additions and 0 deletions
@@ -0,0 +1,159 @@
+# SMAVS
+
+> **SMAVS (Su Misura Al Vostro Sistema)**
+> The Composition Engine developed by **Spiral**.
+
+---
+
+## Overview
+
+SMAVS is a deterministic composition engine designed to transform structured specifications into complete software artifacts through a modular composition pipeline.
+
+Rather than generating code directly, SMAVS analyzes a specification, selects compatible modules, resolves dependencies, builds an execution plan, and composes the final artifact.
+
+The framework is built around the principles of:
+
+- Deterministic execution
+- Modular architecture
+- Composition over inheritance
+- Domain-Driven Design
+- Clean Architecture
+- Layer isolation
+- Dependency inversion
+- Immutability
+
+---
+
+## Architecture
+
+The composition pipeline follows the architecture defined by the Software Architecture Specification (SAS):
+
+```
+JSON
+    │
+    ▼
+FastAPI
+    │
+    ▼
+Application
+    │
+    ▼
+SMAVSEngine
+    │
+    ▼
+Analysis
+    │
+    ▼
+Knowledge
+    │
+    ▼
+Composition
+    │
+    ▼
+Artifact
+```
+
+Each layer communicates exclusively through Contracts.
+
+---
+
+## Repository Structure
+
+```
+smavs/
+
+├── api/
+├── artifacts/
+├── core/
+├── docs/
+├── examples/
+├── modules/
+├── scripts/
+├── shared/
+├── templates/
+└── tests/
+```
+
+---
+
+## Current Status
+
+Current version:
+
+```
+0.1.0 (Foundation)
+```
+
+Current implementation phase:
+
+```
+PHASE 0 — Foundation
+```
+
+Current sprint:
+
+```
+Sprint 0.1 — Repository
+```
+
+---
+
+## Project Goals
+
+SMAVS aims to provide a deterministic engine capable of:
+
+- analyzing project specifications;
+- building composition contexts;
+- resolving module dependencies;
+- selecting compatible variants;
+- composing software artifacts;
+- producing reproducible outputs.
+
+Given the same:
+
+- specification;
+- framework version;
+- module versions;
+
+SMAVS always produces the same artifact.
+
+---
+
+## Technology Stack
+
+- Python 3.12+
+- Domain-Driven Design
+- Clean Architecture
+- SOLID
+- Dataclasses
+- Protocols
+- Pydantic v2 (API only)
+
+---
+
+## Documentation
+
+Project documentation is organized under the `docs/` directory.
+
+It includes:
+
+- Architecture
+- Guides
+- API
+- Contracts
+- Modules
+- Examples
+
+---
+
+## License
+
+This project is licensed under the terms described in the `LICENSE` file.
+
+---
+
+## Developed by
+
+**Spiral**
+
+SMAVS is the proprietary Composition Engine powering the Spiral ecosystem.