first

2026-09-08 07:21:34 -04:00
commit a4b224da8e
169 changed files with 27483 additions and 0 deletions
@@ -0,0 +1,197 @@
+# Azurian Software Factory (ASF)
+
+> From Requirement to Production, everything is contextualized, traceable and AI-accessible.
+
+ASF is an AI-native, multi-tenant **Software Factory delivered as a SaaS platform**.
+
+It creates a persistent contextual and traceability layer connecting the complete software lifecycle:
+
+```
+Requirement → Architecture → Task → Code → Commit → Pull Request → Build
+→ Test → Deployment → Runtime → Incident → Feedback
+```
+
+**Central principle:** *Everything is an Artifact.*
+
+---
+
+## 🏗️ Repository Structure
+
+ASF is organized as a **monorepo**:
+
+```text
+ASF/
+├── AGENT.md                     ← AI engineering rules (MANDATORY READ)
+├── README.md                    ← This file
+├── docker-compose.yml           ← Local infra (Mongo, Rabbit, Redis, MinIO)
+├── .env.example                 ← Environment template
+│
+├── docs/
+│   ├── architecture/            ← Architecture overviews, diagrams
+│   ├── adr/                     ← Architectural Decision Records
+│   └── api/                     ← API documentation
+│
+├── frontend/
+│   └── asf-web/                 ← Next.js + React SaaS frontend
+│
+├── services/
+│   ├── asf-core/                ← FastAPI: orgs, projects, artifacts, jobs, audit
+│   ├── asf-context/             ← Context engine, artifact traversal
+│   ├── asf-ai/                  ← AI Gateway: model abstraction, routing
+│   └── asf-worker/              ← RabbitMQ consumers / async jobs
+│
+├── packages/
+│   ├── asf-domain/              ← Shared Pydantic domain models
+│   ├── asf-events/              ← Event schemas (RabbitMQ payloads)
+│   └── asf-connectors/          ← External system integration interfaces
+│
+├── infrastructure/
+│   ├── docker/                  ← Per-service Dockerfiles
+│   └── scripts/                 ← Dev / bootstrap scripts
+│
+└── tests/                       ← Cross-service integration tests
+```
+
+---
+
+## 🧱 Technology Stack
+
+| Layer       | Stack                                                |
+|-------------|------------------------------------------------------|
+| Frontend    | Next.js · React · TypeScript · Tailwind · shadcn/ui  |
+| Frontend+   | TanStack Query · React Flow · Zustand (sparingly)    |
+| Backend     | Python 3.12+ · FastAPI · Pydantic · async/await      |
+| Database    | MongoDB 7 (async driver)                             |
+| Messaging   | RabbitMQ 3.13 (events + job queues)                  |
+| Cache       | Redis 7                                              |
+| Storage     | MinIO / S3-compatible object storage                 |
+| Testing     | pytest (Python) · Vitest/Jest (TS)                   |
+
+---
+
+## 🚀 Local Development
+
+### Prerequisites
+
+- Docker & Docker Compose
+- Python 3.12+
+- Node.js 20+
+- pnpm or npm
+
+### 1. Start infrastructure
+
+```bash
+cp .env.example .env
+docker compose up -d
+```
+
+This starts:
+- **MongoDB** on `localhost:27017`
+- **RabbitMQ** on `localhost:5672` (management UI on `:15672`)
+- **Redis** on `localhost:6379`
+- **MinIO** on `localhost:9000` (console on `:9001`)
+
+### 2. Install backend packages
+
+```bash
+# Shared domain package
+cd packages/asf-domain && pip install -e . && cd ../..
+cd packages/asf-events && pip install -e . && cd ../..
+cd packages/asf-connectors && pip install -e . && cd ../..
+
+# Core service
+cd services/asf-core && pip install -r requirements.txt && cd ../..
+```
+
+### 3. Run asf-core API
+
+```bash
+cd services/asf-core
+uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
+```
+
+OpenAPI docs:
+- Swagger UI: http://localhost:8000/docs
+- ReDoc:    http://localhost:8000/redoc
+- Health:   http://localhost:8000/api/v1/health
+
+### 4. Install & run frontend
+
+```bash
+cd frontend/asf-web
+npm install
+npm run dev
+```
+
+UI: http://localhost:3000
+
+### 5. Run workers (optional for full async pipeline)
+
+```bash
+cd services/asf-worker
+pip install -r requirements.txt
+python -m app.worker
+```
+
+---
+
+## 🔑 SaaS Multi-Tenancy Model
+
+```
+Organization (tenant boundary)
+  └── Teams
+        └── Projects
+              └── Artifacts + Relationships + Jobs
+```
+
+Every tenant-owned record carries `tenant_id`. Cross-tenant queries are blocked at the service/repository layer.
+
+---
+
+## 🧩 Services Quick Reference
+
+| Service       | Purpose                                                      |
+|---------------|--------------------------------------------------------------|
+| `asf-core`    | REST API · Organizations · Projects · Artifacts · Jobs · Audit |
+| `asf-context` | Context assembly · Relationship traversal · Semantic search  |
+| `asf-ai`      | AI Gateway · Provider abstraction · Usage metering           |
+| `asf-worker`  | RabbitMQ consumers · Async job execution                     |
+| `asf-web`     | Next.js Enterprise SaaS UI shell                             |
+
+---
+
+## 🧪 Testing
+
+```bash
+# Python (all backend services + packages)
+pytest packages/asf-domain/tests
+pytest services/asf-core/tests
+```
+
+---
+
+## 📚 Documentation
+
+- Architecture overview: [docs/architecture/](docs/architecture/)
+- Architectural Decision Records: [docs/adr/](docs/adr/)
+- API docs (auto): http://localhost:8000/docs
+- AGENT.md (MANDATORY engineering rules for contributors): [AGENT.md](AGENT.md)
+
+---
+
+## 🛡️ Security
+
+- Never commit `.env`, credentials, or private keys.
+- Never expose infrastructure connections to the frontend.
+- All tenant-scoped queries are validated against authenticated context.
+- Audit events are written for sensitive mutations.
+
+---
+
+## 🤝 Guiding Question
+
+When contributing any feature, ask:
+
+> *Does this improve the connection between software context, traceability, automation and AI?*
+
+If not — reconsider the implementation.