12 KiB
AGENT.md
Azurian Software Factory - AI Engineering Rules
This file defines mandatory rules for AI coding agents working on the Azurian Software Factory repository.
Read this document before modifying code.
1. Product Identity
Product:
Azurian Software Factory (ASF)
Tagline:
From Requirement to Production, everything is contextualized, traceable and AI-accessible.
ASF is an AI-native, multi-tenant Software Factory SaaS.
ASF connects the complete software lifecycle:
Requirement → Architecture → Task → Code → Commit → Pull Request → Build → Test → Deployment → Runtime → Incident → Feedback.
ASF is not merely an AI coding assistant.
2. Core Principle
The central ASF principle is:
Everything is an Artifact.
Requirements, architecture decisions, documents, source code references, commits, tests, builds, deployments, incidents and AI analyses can all be represented as Artifacts.
Artifacts may have relationships with other Artifacts.
Never implement functionality that unnecessarily breaks this generic model.
3. Architectural Principles
All implementations must preserve:
- Multi-tenancy
- Traceability
- Context preservation
- API-first design
- Event-driven architecture
- AI provider independence
- Integration provider independence
- Horizontal scalability
- Auditability
- Security by design
4. Technology Baseline
Backend
Use:
- Python 3.12+
- FastAPI
- Pydantic
- async/await
- MongoDB
- RabbitMQ
- Redis
- MinIO/S3
Do not introduce another primary database without an ADR.
Frontend
Use:
- Next.js
- React
- TypeScript
- Tailwind CSS
- shadcn/ui
- TanStack Query
- React Flow
Use Zustand only where persistent/shared client state is genuinely necessary.
AI
All model access must go through the ASF AI Gateway abstraction.
Never call a specific LLM provider directly from domain/business code.
Messaging
RabbitMQ is the primary event and asynchronous messaging backbone.
MongoDB is the persistent source of truth for job state.
5. Multi-Tenancy
Every tenant-owned entity must contain tenant_id.
Where appropriate it must also contain project_id.
Never trust tenant identity supplied directly by a browser request.
Tenant context must come from validated authentication/authorization context.
Every database query involving tenant-owned data must be tenant scoped.
Cross-tenant data leakage is considered a critical defect.
Tests must cover tenant isolation for sensitive operations.
6. Artifact Rules
Prefer the generic Artifact model for lifecycle entities.
Artifact types may include:
- requirement
- epic
- story
- task
- architecture_decision
- document
- source_file
- commit
- pull_request
- build
- test
- deployment
- release
- security_finding
- runtime_event
- incident
- ai_analysis
Do not create a new MongoDB collection for every artifact type unless there is a documented architectural reason.
Artifact metadata must remain extensible.
7. Relationships
Artifact relationships must be explicit and queryable.
Examples:
- implements
- implemented_by
- verifies
- verified_by
- generated_from
- documented_by
- depends_on
- affects
- deployed_as
- caused_by
- supersedes
- related_to
Do not encode important traceability relationships only inside free text.
8. Context
AI operations must receive relevant context through the ASF Context Engine.
Do not build arbitrary RAG logic directly inside API endpoints or UI code.
Context retrieval must remain independently evolvable.
The architecture must allow future integration of:
- embeddings
- vector search
- graph traversal
- source code indexing
- document indexing
- runtime telemetry
9. AI Rules
ASF must remain model agnostic.
Supported architectures may include:
- DGX-hosted models
- OpenAI-compatible APIs
- external providers
- future customer-hosted models
Model selection belongs to the AI Gateway.
Business services request capabilities, not specific model implementations.
Prefer concepts such as:
analyze_code()
over:
call_qwen()
unless inside a provider adapter.
Record AI usage when technically available.
Never expose model credentials to frontend code.
10. Queue Rules
Separate interactive and background workloads.
Typical queues:
- asf.ai.interactive
- asf.ai.background
- asf.indexing
- asf.code_analysis
- asf.testing
- asf.devops
- asf.notifications
Interactive user requests should receive higher scheduling priority than non-critical background work.
Workers must be stateless where practical and horizontally scalable.
Do not rely on process memory for persistent job state.
Consumers must be designed for duplicate delivery.
Where side effects occur, use idempotency mechanisms.
Do not assume exactly-once delivery.
11. Event Rules
Events describe facts that happened.
Prefer:
artifact.created
requirement.updated
deployment.completed
instead of ambiguous event names.
Every distributed event should contain sufficient metadata for tracing, including where applicable:
- event_id
- event_type
- timestamp
- tenant_id
- project_id
- correlation_id
- causation_id
- payload
Do not place large binary content directly in RabbitMQ messages.
Store large content in MinIO and transmit a reference.
12. MinIO Rules
Use MinIO/S3 for:
- uploaded documents
- generated files
- large reports
- repository archives where appropriate
- large AI inputs/outputs where persistence is required
MongoDB should store metadata and object references.
Do not store large binary objects directly in normal MongoDB documents unless specifically justified.
13. API Rules
REST API prefix:
/api/v1
Health endpoint:
GET /api/v1/health
Use:
- Pydantic request/response models
- explicit validation
- consistent HTTP status codes
- consistent error responses
Do not expose MongoDB internal structures directly through APIs.
Do not put business logic directly inside FastAPI route functions.
Routes should delegate to application/domain services.
14. Python Rules
Use type hints.
Prefer async I/O for:
- MongoDB
- RabbitMQ
- Redis
- HTTP
- MinIO operations where supported
Keep functions focused.
Avoid giant service classes.
Avoid hidden global state.
Use dependency injection where it improves testing and separation.
Do not catch Exception unless there is a deliberate boundary-level reason.
Never silently ignore errors.
15. Frontend Rules
Frontend components must not contain backend business rules.
Never access MongoDB, RabbitMQ, Redis or MinIO directly from the browser.
Use the ASF API.
Pages must support:
- loading state
- empty state
- error state
Do not present mocked data as production data.
Traceability visualization must use reusable node/edge components.
The UI must remain responsive and accessible.
16. Security Rules
Never commit:
- passwords
- API keys
- private keys
- tokens
- certificates
- production credentials
Use environment configuration.
Provide .env.example containing names and safe placeholder values only.
Never log authentication secrets.
Validate uploaded files.
Validate external connector input.
Assume external webhook payloads are untrusted.
17. Logging and Observability
Use structured JSON logging on backend services.
Propagate where applicable:
- correlation_id
- tenant_id
- project_id
- job_id
Prepare services for OpenTelemetry instrumentation.
Logs are operational telemetry.
Audit events are business/security records.
Do not confuse the two concepts.
18. Connectors
External systems must be isolated behind connector interfaces.
Examples:
- GitHub
- GitLab
- Bitbucket
- Jira
- Confluence
- Notion
- Jenkins
- SonarQube
- Grafana
Do not spread provider-specific APIs throughout ASF business code.
MCP should be preferred where it provides a suitable standardized capability.
REST and Webhooks remain supported integration mechanisms.
19. Testing Rules
Backend tests use pytest.
Tests should cover:
- domain logic
- API behavior
- artifact relationships
- job state transitions
- event handling
- tenant isolation
Bug fixes should include regression tests where practical.
Do not remove failing tests merely to make the build green.
20. Database Rules
MongoDB is the primary ASF datastore.
Collections and indexes must be intentionally designed.
Common queries must have appropriate indexes.
Tenant-aware compound indexes should be considered.
Schema flexibility does not mean schema absence.
Pydantic models define application-level contracts.
Database migrations or data transformation scripts must be versioned.
21. Architectural Decisions
Significant architectural decisions require an ADR under:
docs/adr/
Examples:
- introducing a new database
- introducing a new message broker
- changing tenancy strategy
- changing authentication architecture
- introducing a graph database
- changing artifact representation
- replacing the AI Gateway
- changing event semantics
Do not make major architectural changes silently.
22. Code Changes
Before modifying code:
- Understand the requested change.
- Inspect relevant existing code.
- Identify affected modules.
- Check existing tests.
- Preserve architectural boundaries.
After modifying code:
- Run relevant tests.
- Run lint/type checks where configured.
- Fix failures introduced by the change.
- Review tenant isolation.
- Review error handling.
- Update documentation when behavior or architecture changed.
23. Dependency Policy
Do not add dependencies unnecessarily.
Before introducing a library, determine whether:
- the standard library already solves the problem
- an existing project dependency solves it
- the new dependency is actively maintained
- it introduces security or licensing concerns
Major framework additions require justification.
24. Simplicity
Do not over-engineer ASF.
Prefer:
simple → testable → observable → scalable
over:
complex → theoretical → difficult to operate.
Microservices are not a goal.
Service boundaries must exist because they provide operational or domain value.
25. Current Logical Components
The initial architecture consists of:
asf-core
Core API, organizations, projects, artifacts, relationships, jobs and audit.
asf-context
Context assembly, relationship traversal and future semantic retrieval.
asf-ai
AI Gateway, provider abstraction, routing and usage.
asf-worker
RabbitMQ consumers and asynchronous processing.
asf-web
Next.js SaaS frontend.
Do not create additional services unless there is a clear reason.
26. Source of Truth
MongoDB: structured application/domain state.
MinIO: large files and binary artifacts.
RabbitMQ: events and work delivery.
Redis: temporary/cache/coordination state.
AI models: never considered authoritative sources of ASF business data.
27. AI Generated Changes
AI-generated code is subject to exactly the same engineering standards as human-written code.
Never assume generated code is correct.
Validate:
- imports
- APIs
- library versions
- async behavior
- security
- tenancy
- error handling
- tests
Never invent an API from an external dependency when its actual interface can be inspected.
28. Definition of Done
A change is not complete merely because code was generated.
A change is complete when:
- implementation works
- relevant tests pass
- tenant isolation is preserved
- errors are handled
- observability is maintained
- architecture rules are respected
- documentation is updated where necessary
- no credentials or sensitive data were introduced
29. Guiding Question
When implementing any ASF feature, ask:
Does this improve the connection between software context, traceability, automation and AI?
If the feature bypasses those principles, reconsider the implementation.