705 lines
12 KiB
Markdown
705 lines
12 KiB
Markdown
# 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. |