asf/README.md

# 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.