# Azurian Software Factory (ASF) - SaaS Platform Bootstrap

You are the lead software architect and senior full-stack engineer responsible for creating the initial foundation of **Azurian Software Factory (ASF)**.

## Product Vision

ASF is an AI-native Software Factory delivered as a multi-tenant SaaS platform.

Tagline:

> From Requirement to Production, everything is contextualized, traceable and AI-accessible.

ASF is NOT simply an AI coding assistant.

ASF creates a persistent contextual and traceability layer connecting:

Requirement → Architecture → Task → Code → Commit → Pull Request → Build → Test → Deployment → Runtime → Incident → Feedback

The central principle is:

> Everything is an Artifact.

Every relevant element of the software lifecycle must be represented as an ASF Artifact and may have relationships with other artifacts.

The platform must allow AI agents to understand not only source code, but WHY the code exists, which requirement originated it, how it was tested, where it was deployed, and what happened during runtime.

---

# 1. Technology Stack

Use the following stack.

## Frontend

- Next.js
- React
- TypeScript
- Tailwind CSS
- shadcn/ui
- TanStack Query
- Zustand only when client-side global state is actually necessary
- React Flow for traceability/context graphs
- SSE or WebSocket for real-time updates

The frontend must be:

- responsive
- desktop optimized
- usable on tablets
- mobile friendly
- component based
- accessible
- suitable for an enterprise SaaS application

Do not access MongoDB directly from Next.js.

All business operations must go through ASF backend APIs.

## Backend

Use:

- Python 3.12+
- FastAPI
- Pydantic
- async/await
- MongoDB
- official async MongoDB driver
- RabbitMQ
- Redis
- MinIO/S3-compatible object storage

The backend must be designed API-first.

## Messaging

RabbitMQ is the ASF event backbone.

It must support both:

1. asynchronous jobs
2. domain events

Examples:

- requirement.created
- requirement.updated
- artifact.created
- artifact.updated
- code.analysis.requested
- code.analysis.completed
- repository.index.requested
- repository.index.completed
- ai.inference.requested
- ai.inference.completed
- test.requested
- test.completed
- deployment.started
- deployment.completed

Do not tightly couple producers to consumers.

## AI

Create an abstraction called:

`ASF AI Gateway`

No ASF service should depend directly on a specific LLM provider.

The AI Gateway will eventually support:

- NVIDIA DGX Spark hosted models
- OpenAI-compatible local APIs
- external AI providers
- model routing
- tenant AI policies
- usage metering
- priority queues
- cost tracking

For the first implementation, create interfaces and mock implementations where necessary.

Do not hardcode a particular model into business logic.

## Integration

ASF must support:

- MCP
- REST APIs
- Webhooks

External systems such as Git providers, requirement management systems, CI/CD platforms, documentation platforms and observability tools must be implemented through connectors.

The ASF Core must not become tightly coupled to Jira, GitHub, GitLab, Jenkins, SonarQube, Notion or similar products.

---

# 2. Core Domain

Implement the initial domain model.

Main entities:

- Organization
- User
- Team
- Project
- Artifact
- ArtifactRelationship
- Integration
- Job
- AIExecution
- AuditEvent

Every tenant-owned entity must include:

- tenant_id
- created_at
- updated_at

where applicable.

Never trust a tenant ID supplied by the client without validating it against the authenticated context.

---

# 3. Artifact Model

Artifact is one of the most important entities in ASF.

Example artifact types:

- requirement
- epic
- story
- task
- architecture_decision
- document
- source_file
- commit
- pull_request
- build
- test
- security_finding
- deployment
- release
- runtime_event
- incident

Design Artifact to support extensible metadata.

Conceptually:

Artifact

- id
- tenant_id
- project_id
- type
- external_id
- title
- content
- source
- metadata
- relationships
- version
- created_at
- updated_at

Do not create separate rigid database models for every possible artifact type unless there is a strong domain reason.

ASF must remain extensible.

---

# 4. Traceability

Artifacts can have relationships such as:

- implements
- implemented_by
- verifies
- verified_by
- generated_from
- documented_by
- depends_on
- affects
- deployed_as
- caused_by
- supersedes
- related_to

Create APIs allowing relationships to be created, queried and traversed.

Example:

REQ-142
→ implemented_by
→ TASK-871
→ implemented_by
→ COMMIT-a87f1c
→ verified_by
→ TEST-882
→ deployed_as
→ RELEASE-2.4

Design this so that a graph database could eventually be introduced without rewriting the entire application.

MongoDB is the initial source of truth.

---

# 5. Context Engine

Create an `asf-context` module/service responsible for assembling context for AI operations.

Given an artifact, project or user request, it should eventually be able to retrieve:

- related requirements
- architecture decisions
- relevant source code
- documentation
- tests
- deployments
- previous AI analysis
- incidents
- runtime information

For the MVP, implement the interfaces and basic MongoDB relationship traversal.

Keep semantic/vector retrieval behind an abstraction so a vector engine can be introduced later.

---

# 6. Job System

Create a persistent Job model.

A job should include at minimum:

- id
- tenant_id
- project_id
- type
- priority
- status
- requested_by
- worker
- model
- correlation_id
- created_at
- started_at
- completed_at
- error
- usage

Usage may contain:

- input_tokens
- output_tokens
- gpu_seconds
- estimated_cost

Suggested statuses:

- queued
- running
- completed
- failed
- cancelled

RabbitMQ contains work messages.

MongoDB contains persistent job state.

Do not treat RabbitMQ as the permanent job database.

---

# 7. Queue Strategy

Prepare separate logical queues for workloads such as:

- asf.ai.interactive
- asf.ai.background
- asf.indexing
- asf.code_analysis
- asf.testing
- asf.devops
- asf.notifications

Interactive developer requests must be capable of receiving higher priority than background indexing jobs.

Workers must be horizontally scalable.

Do not maintain critical worker state only in process memory.

---

# 8. SaaS Requirements

ASF must be multi-tenant from the beginning.

Design for:

Organization
→ Teams
→ Projects
→ Artifacts

Prepare the architecture for:

- RBAC
- SSO
- API keys
- audit
- quotas
- usage metering
- subscriptions
- billing

Full billing implementation is NOT required in the first bootstrap.

Create boundaries/interfaces so it can be introduced cleanly.

---

# 9. Frontend

Create an enterprise SaaS shell.

Main navigation:

- Overview
- Requirements
- Context
- Code
- Traceability
- AI Agents
- Pipelines
- Deployments
- Quality
- Observability
- Integrations
- Usage
- Settings

Create organization and project selectors.

## Overview

Initial project dashboard should support cards for:

- project health
- requirements
- implementation coverage
- test coverage
- traceability
- deployments
- active AI jobs
- failed builds
- security findings

Mock unavailable metrics initially.

Clearly identify mocked/demo data.

## Context Explorer

Create an initial Context Explorer where a user can select an Artifact and inspect:

- metadata
- relationships
- related artifacts
- source
- history

## Traceability

Use React Flow to visualize artifact relationships.

Example:

Requirement
→ Task
→ Pull Request
→ Test
→ Build
→ Deployment

Nodes must be clickable.

## Ask ASF

Create a persistent command/chat interface accessible from the application shell.

Concept:

`Ask ASF...`

Future queries include:

- Show requirements without tests.
- Why did yesterday's build fail?
- Which services implement REQ-441?
- What will be affected if REQ-441 changes?
- Generate tests for TASK-921.

For now create the UI and backend interface.

Do not fake AI answers as if they were real production analysis.

---

# 10. Repository Structure

Start with a monorepo.

Suggested structure:

```text
asf/
├── AGENT.md
├── README.md
├── docs/
│   ├── architecture/
│   ├── adr/
│   └── api/
│
├── frontend/
│   └── asf-web/
│
├── services/
│   ├── asf-core/
│   ├── asf-context/
│   ├── asf-ai/
│   └── asf-worker/
│
├── packages/
│   ├── asf-domain/
│   ├── asf-events/
│   └── asf-connectors/
│
├── infrastructure/
│   ├── docker/
│   └── scripts/
│
└── tests/
```

Do not create microservices merely for architectural appearance.

Initially keep service boundaries pragmatic.

---

# 11. Initial Services

## asf-core

Responsible for:

- organizations
- projects
- artifacts
- relationships
- jobs
- audit
- public REST API

## asf-context

Responsible for:

- context assembly
- artifact traversal
- future semantic retrieval

## asf-ai

Responsible for:

- AI Gateway
- model abstraction
- inference routing
- usage tracking

## asf-worker

Responsible for:

- RabbitMQ consumers
- asynchronous execution
- background jobs

---

# 12. Observability

Use structured JSON logging.

Every distributed operation should propagate:

- correlation_id
- tenant_id
- project_id
- job_id when applicable

Prepare the architecture for OpenTelemetry.

Never log:

- passwords
- API keys
- access tokens
- private secrets
- complete authentication headers

---

# 13. API Standards

Use REST initially.

API prefix:

`/api/v1`

Provide:

`GET /api/v1/health`

Use consistent error structures.

Generate OpenAPI documentation automatically through FastAPI.

Use UUIDs for internal identifiers unless there is a documented reason not to.

---

# 14. Security

Security must not be postponed until production.

Apply:

- tenant isolation
- input validation
- secret separation
- authorization boundaries
- secure defaults
- audit logging

Never store secrets directly inside source code.

Use environment variables/configuration for secrets.

Never expose infrastructure credentials to the frontend.

---

# 15. Engineering Rules

Follow SOLID principles where useful, but avoid unnecessary abstraction.

Prefer:

- simple code
- explicit interfaces
- dependency injection
- typed models
- testable components
- clear boundaries

Avoid:

- premature optimization
- excessive microservices
- giant service classes
- hidden global state
- provider-specific logic inside the domain layer
- unnecessary framework wrappers

---

# 16. Testing

Create the foundation for:

- unit tests
- API integration tests
- worker tests
- tenant isolation tests

Use pytest for Python.

Critical domain logic must have tests.

---

# 17. Documentation

Create:

- README.md
- local development instructions
- architecture overview
- environment variable example
- initial API documentation
- ADR directory

Architecture decisions that materially affect ASF must be documented as ADRs.

---

# 18. Bootstrap Objective

Do NOT attempt to implement the complete ASF product in one pass.

The first objective is to produce a clean, runnable foundation containing:

1. repository structure
2. FastAPI backend
3. MongoDB connectivity
4. RabbitMQ connectivity
5. Redis connectivity
6. MinIO connectivity
7. Organization model
8. Project model
9. Artifact model
10. Artifact Relationship model
11. Job model
12. CRUD APIs for the essential entities
13. basic RabbitMQ producer/consumer
14. AI Gateway abstraction
15. Context Engine abstraction
16. Next.js application shell
17. initial Overview page
18. initial Artifact Explorer
19. initial React Flow Traceability view
20. Ask ASF UI shell
21. health endpoints
22. tests
23. documentation

Everything must run locally for development.

---

# 19. Before Coding

Before generating large amounts of code:

1. Inspect the existing repository.
2. Read `AGENT.md`.
3. Do not overwrite useful existing work.
4. Produce a short implementation plan.
5. Identify architectural assumptions.
6. Then implement incrementally.
7. Run tests after meaningful changes.
8. Fix failures before continuing.

When uncertain, prefer the simplest architecture compatible with the ASF principles.