SRA (System Requirements Analyzer)

SRA is an enterprise-grade, AI-orchestrated ecosystem designed to formalize the software requirements engineering lifecycle. By combining Large Language Model (LLM) reasoning with rigorous architectural standards, SRA transforms fragmented project visions into high-fidelity, production-ready technical specifications — in IEEE 830-1998, ISO/IEC/IEEE 29148:2018, Volere or Agile PRD form — and traces them back to the code that implements them.

---

🔗 Quick Links

Resource	URL	Description
Live Application	sra-xi.vercel.app	Production frontend deployment
Architecture Guide	ARCHITECTURE.md	System architecture & design
Operations Manual	OPERATIONS.md	Deployment, backup & DR procedures
Contributing	CONTRIBUTING.md	Development setup & guidelines
Modernization Record	docs/MODERNIZATION.md	Findings, fixes, and deferred work from the latest audit pass

---

🏛️ Summary

Industry research, including PMI and other studies, indicates that a significant portion of project failures, often estimated between 30% and 50%, can be traced back to poor requirements engineering, including unclear documentation, semantic ambiguity, and stakeholder misalignment. SRA mitigates this risk by providing an automated, multi-layered validation and synthesis engine.

Core Value Propositions

• Zero-Ambiguity Intake: Standardizes raw stakeholder descriptions into structured architectural models.
• AI-Driven Governance: Real-time logic checking to identify contradictions, missing logic, and technical gaps.
• High-Fidelity Visuals: Automated generation of multi-level Data Flow Diagrams (DFD) and system-level Mermaid diagrams.
• Semantic Intelligence: Leverages vector-based knowledge retrieval (RAG) and Graph-Hybrid Search to ensure consistency across complex project portfolios.
• Intelligent Requirement Recycling: Proactively suggests high-quality requirement fragments from past "Gold Standard" projects to accelerate new SRS drafting.
• Objective Quality Auditing: Real-time scoring against the 6Cs of Requirements Quality (Clarity, Completeness, etc.).
• Industry Benchmarking: Integrated RAG evaluation for Faithfulness and Answer Relevancy.

---

🔄 The 5-Layer Analysis Pipeline

SRA operates on a proprietary 5-layer pipeline that ensures every requirement is processed through a rigid quality-control sequence.

graph TD
    subgraph "Cloud Analysis Layer (SRA Platform)"
        L1[<b>Layer 1: Strategic Intake</b><br/>Unstructured Input Mapping]
        L2[<b>Layer 2: MAS Analysis</b><br/>PO, Architect, & Dev Agents]
        L3[<b>Layer 3: Objective Review</b><br/>6Cs Audit & RAG Evaluation]
        L4[<b>Layer 4: Refinement Hub</b><br/>Live Workspace & Diff Tracking]
        L5[<b>Layer 5: Knowledge Persistence</b><br/>Semantic Indexing & Hybrid Search]

        Reliability[(<b>Reliability Layer</b><br/>Stage Chaining, Checkpoints & Jittered Retries)]
        L2 & L3 -.-> Reliability
    end

    subgraph "Local Execution Layer (CLI Toolkit)"
        CLI["SRA CLI (@sra-srs/sra-cli)"] -->|Auth/Sync| L1
        CLI -->|Reverse: codebase digest| L1
        CLI -->|Verify| Code[(Local Source Code)]
        Code -->|Verification Data| CLI
        CLI -->|Push Traceability| L4
    end

    Stakeholder((Stakeholder)) -->|Raw Vision| L1
    L1 --> L2
    L2 --> L3
    L3 -->|FAIL: Poor Score| L2
    L3 -->|PASS| L4
    L4 -->|Export| Artifacts[SRS Document, DOCX, DFD, Diagrams]
    L4 --> L5

The pipeline runs entirely server-side and survives the browser being closed: work is checkpointed per stage, and an invocation that runs out of its serverless budget re-enqueues itself and resumes from the last checkpoint rather than restarting or truncating.

1. Strategic Intake: Translates free-text into a mapped JSON model aligned with IEEE section hierarchies.
2. Multi-Agent Analysis: Orchestrates specialized AI agents (Product Owner, Architect, Developer) using the v2.1.0 Gold Standard prompt registry.
3. Objective Review: Automated auditing of SRS content against the 6Cs and RAG evaluation for contextual faithfulness.
4. Iterative Refinement: A modular Workspace UI for manual adjustments, version branching, and intelligent diagram repair.
5. Knowledge Persistence: Finalized requirements are "shredded" and indexed into a PostgreSQL + pgvector graph for cross-project intelligence.

---

✨ Enterprise Feature Modules

📊 Professional Requirements Engineering

• Four Specification Standards: IEEE 830-1998, ISO/IEC/IEEE 29148:2018, Volere, and Agile PRD. The chosen format drives generation, rendering, export and CLI round-trip end to end from a single descriptor — see backend/src/formats/ and GET /api/formats.
• IEEE-830 Compliance: Automated generation with strict identifier governance and academic prose discipline.
• 6Cs Quality Audit: Automated internal scoring for Clarity, Completeness, Conciseness, Consistency, Correctness, and Context — gates every draft in the Reviewer/Critic reflection loop before it reaches the user.
• RAG Benchmarking: Real-time evaluation of LLM Faithfulness and Answer Relevancy.
• User Story Evolution: Generates "Jira-Ready" user stories with granular acceptance criteria.

🔑 Bring Your Own Key (BYOK) & Model Choice

• Multi-Provider Support: Gemini, OpenAI, Claude, and Grok.
• BYOK on Every Provider, Including Gemini: Generation has no platform-funded fallback. The platform's own Gemini key funds embeddings only — the pgvector columns are one shared embedding space that cannot be per-user. Enqueue, chat and the UI all gate on a configured key.
• Encrypted Key Storage: User-supplied keys are AES-256-GCM encrypted at rest and never returned in plaintext by the API — only a masked preview is shown back.
• Model Discovery Tied to the Key: The model list offered is the one that specific key can actually call, discovered on save, with per-model token ceilings used to size generation budgets.
• Per-Analysis Model Selection: Choose provider and specific model (e.g. Gemini 2.5 Flash/Pro, GPT-5.6, Claude Opus 4.8/Sonnet 5, Grok 4.5) when starting a new analysis.
• Fixed Embedding Provider: RAG embeddings always run on Gemini regardless of the chosen generation provider, since the vector column is dimensioned to its embedding model.

🎨 Advanced Architectural Visualization

• Multi-Level DFDs: Generates Level 0 (Context) and Level 1 (Functional Decomposition) Gane-Sarson diagrams.

• Interactive Explorer: Powered by @xyflow/react with support for high-fidelity PNG Export.

• Self-Healing Diagrams: Integrated Mermaid Repair Engine that identifies and fixes syntax errors in generated UML.

🔒 Security, Privacy & Governance

• Proactive PII Redaction: Automated sanitization of user intent (Emails, Phone, CC) before processing by external AI providers.
• RBAC Architecture: Secure access control with JWT integration and social OAuth (Google/GitHub).
• Revision History: Complete versioning system with visual diff tracking between requirement updates.
• Audit-Ready Exports: One-click professional PDF generation with table of contents and revision logs.

🛠️ SRA CLI Toolkit (v4.2.2)

• Spec-to-Code Traceability: Requirement groups link to the source files that implement them, surfaced back on the web workspace for every format.
• Reverse Engineering: sra reverse reduces an existing codebase to a structural digest — interfaces, entities, module layout, dependencies — runs it through the same multi-agent pipeline, and proposes source links for the requirements it produces.
• Local Compliance Engine: sra check confirms links resolve; --deep re-checks that the linked files still carry the requirement's own identifiers, catching links that rotted as code moved.
• Live Pipeline Progress: sra analyze and sra status --watch stream real pipeline stages over the platform's SSE channel, falling back to polling when live progress is unavailable.
• Format-Aware Round-Trip: Reads the format registry from the platform, so sync/push never write IEEE's sections into a Volere, ISO 29148 or Agile PRD document.
• System Diagnostics: sra doctor validates environment, credentials, connectivity, and whether a BYOK provider key is actually configured.

---

🛡️ Production Hardening

SRA is engineered for stability, security, and enterprise-grade performance.

🧩 Infrastructure Security

• Multi-Stage Docker Builds: Minimized production images using separate build/runtime environments.
• Non-Root Execution: Containers run as unprivileged users (nodejs/nextjs) to mitigate security risks.
• Dependency Pinning: Strict versioning of core dependencies (e.g., Next.js 16.1.6) to ensure environment parity.

🌐 Network & Content Security

• Hardened CSP: Strict Content Security Policy injected via Next.js and Express security headers.
• HSTS & Frame Protection: Production-grade Strict-Transport-Security and X-Frame-Options (DENY/SAMEORIGIN) enforcement.
• Secure Session Management: JWT-based authentication with secure cookie handling.
• Privacy Sanitization: Integrated sanitizer.js layer to prevent data leakage to LLM providers.
• Distributed Rate Limiting: Redis-backed throttling ensures global protection across all server instances.

🔍 AI Reliability & Performance optimization

• AI Reliability Layer: Implemented a standardized BaseAgent with a 6-minute timeout, jittered retries, and high-fidelity JSON parsing logs for stable long-form document generation.
• Frontend Code Splitting: Transitioned to an "Archive-First" dynamic loading strategy using next/dynamic. Components like ResultsTabs and their individual sub-tabs are lazy-loaded to minimize initial JS payload and improve TBT.
• Redis Caching: High-traffic endpoints (Dashboard) cached via Upstash for sub-millisecond retrieval.
• Automated SEO: Dynamic sitemap.xml and robots.txt generation for search engine discoverability.
• Graceful Shutdown: Native handling of SIGTERM/SIGINT to ensure zero-downtime deployments.
• Standalone Mode: Next.js optimized standalone output.
• Smart Data Fetching: SWR-based caching and background revalidation.

🔐 Backup & Disaster Recovery

• Automated Encrypted Backups: Weekly automated database backups with AES-256-GCM encryption.
• Point-in-Time Recovery: 7-day PITR via Supabase for granular data restoration.
• CLI Backup Management: Command-line tools for manual backup creation, restoration, and verification.
• Multi-Location Storage: Backups stored locally, in GitHub Artifacts, and Supabase snapshots.
• Integrity Verification: SHA-256 checksums ensure backup file integrity.

�️ Security Monitoring & Audit

• Comprehensive Audit Logging: Tracks all sensitive operations (create, delete, export) with full metadata.
• Threat Detection: Real-time monitoring for brute force attempts, mass deletions, and unusual access patterns.
• Field-Level Encryption: PII data encrypted at rest using AES-256-GCM.
• Daily Security Audits: Automated dependency scanning, secret leak detection, and security header validation.
• Compliance Ready: Audit trails and security reports for regulatory compliance.

---

🚀 CI/CD & Monitoring

SRA leverages professional GitHub Actions for continuous quality assurance and operational excellence.

🔄 Continuous Integration & Delivery

• Automated Docker Builds: Multi-stage Docker builds triggered on every push to main, publishing optimized images to GHCR.
• Bundle Size Monitoring: Tracks and reports JavaScript bundle size changes for the Next.js frontend, preventing performance regressions.
• Linting & Formatting: Enforces consistent code style and catches potential errors early in the development cycle.
• API Contract Testing: A version-controlled Bruno collection (bruno/) exercises the auth/project/analysis/settings routes against a real running backend on every PR, catching route-level regressions the Jest suite's mocked tests can't.

🩺 Health & Security Monitoring

• Scheduled Health Checks: Hourly automated uptime verification of the entire SRA pipeline.
• Real-time Observability: Dedicated /api/health endpoint for deep system diagnostics (DB, AI Provider).
• Docker Healthchecks: Infrastructure-aware readiness probes ensure the frontend only serves traffic once the backend is fully initialized.
• CodeQL Security Scans: Proactive identification of security vulnerabilities and common coding errors.
• Dependency Vulnerability Checks: Scans for known vulnerabilities in project dependencies.
• Automated Backup Verification: Weekly encrypted database backups with integrity validation.
• Daily Security Audits: Comprehensive security posture checks including secret leak detection and permission audits.

---

💻 Tech Stack & Rationale

Component	Technology	Rationale
Frontend	Next.js 16.1.6	App Router with standalone output for enterprise scalability.
Styling	Tailwind CSS v4	Next-gen JIT engine for high-performance, responsive UI.
Backend	Node.js 24 LTS / Prisma 7	Type-safe ORM for robust asynchronous data orchestration.
Database	PostgreSQL 16+	High-concurrency persistence with pgvector RAG support.
Orchestration	Upstash QStash	Serverless job queue for reliable, long-running AI tasks.
LLM Engine	Multi-provider (Gemini default, BYOK OpenAI/Claude/Grok)	Gemini runs on the platform's own key for every user out of the box; users can add their own OpenAI, Claude, or Grok key in Settings and pick a provider + model per analysis.

---

🏗️ Infrastructure as Code

SRA uses Terraform to manage cloud infrastructure declaratively, ensuring reproducibility, disaster recovery, and version-controlled infrastructure changes.

Infrastructure Management

All infrastructure configuration is defined in the terraform/ directory:

terraform/
├── main.tf                    # Provider & backend configuration
├── variables.tf               # Variable definitions
├── vercel.tf                  # Vercel project resources
├── outputs.tf                 # Output values
├── terraform.tfvars.example   # Configuration template
└── README.md                  # Detailed usage guide

Managed Resources

Terraform manages the following infrastructure:

• ✅ Vercel Projects: Monorepo with frontend (sra) and backend (sra-backend)
• ✅ Build Configuration: Build/install commands and framework settings
• ✅ Git Integration: Repository connections and deployment triggers

Note: Environment variables are managed directly in Vercel dashboard to avoid storing secrets in Terraform state.

Quick Start

# Navigate to terraform directory
cd terraform

# Initialize Terraform
terraform init

# Preview infrastructure changes
terraform plan

# Apply changes (when ready)
terraform apply

Benefits

• 🔄 Version Control: Infrastructure changes tracked in git
• 🛡️ Disaster Recovery: Rebuild entire infrastructure with one command
• 📝 Documentation: Infrastructure is self-documenting code
• 🔍 Audit Trail: Complete history of infrastructure changes
• 🤝 Collaboration: Team members can propose infrastructure changes via PRs

For detailed Terraform usage, see terraform/README.md.

---

⚙️ Operational Guide & Deployment

1. Advanced Environment Configuration

Ensure the following variables are defined in your infrastructure (see .env.example files in backend/ and frontend/ for details):

Group	Key	Required	Description
Database	DATABASE_URL	Yes	Postgres connection string with transaction pooling (typically port 6543).
Database	DIRECT_URL	Yes	Direct connection string bypassing transaction pooler (typically port 5432) for Prisma migrations and heavy-duty database backup/restore operations.
Database	REDIS_URL	Optional	Redis connection string for rate limiting/caching.
AI (Gemini)	GEMINI_API_KEY	Yes	The only provider credential the platform holds, and it funds embeddings only. Embeddings are fixed to Gemini regardless of which generation provider a user picks, because the pgvector columns are one shared embedding space.
AI (Gemini)	RAG_SIMILARITY_THRESHOLD	Optional	Cosine similarity threshold for RAG retrieval matching, defaults to 0.25.
AI (models)	GEMINI_MODEL_NAME, GEMINI_UTILITY_MODEL_NAME, GEMINI_EMBEDDING_MODEL, GEMINI_EMBEDDING_DIMENSIONS	Yes (embeddings pair), otherwise default fallbacks	No model id is hardcoded in src/ — read from the environment via backend/src/config/models.js, so a retired model is an env edit plus a restart. GEMINI_EMBEDDING_DIMENSIONS must equal the vector(N) width in schema.prisma. Gemini is the only provider with a server-side default: the platform runs it for embeddings and internal utility calls. There is no OPENAI_MODEL_NAME/CLAUDE_MODEL_NAME/GROK_MODEL_NAME here — those are BYOK-only and must come from the user's own request.
AI (BYOK)	(none)	—	There are deliberately no platform OpenAI/Anthropic/xAI keys. Every generation-side call — generation, validation gate, auto-fix, alignment, refinement, feature expansion, diagram repair, graph extraction, RAG scoring — runs on the requesting user's own key, added via and stored encrypted (AES-256-GCM) per user.

2. Deployment Strategies

🐳 Docker Orchestration (Recommended)

SRA is fully containerized for cloud-agnostic deployment. Our CI pipeline automatically publishes production-ready images to GitHub Container Registry (GHCR).

# Pull and run the latest images via Compose
docker compose up --build -d

• API Service: http://localhost:3000 (Optimized Multi-stage Build)
• Application UI: http://localhost:3001 (Next.js Standalone Build)

⌨️ CLI (v4.2.2)

The SRA toolkit operates cross-workspace for unified project control. See cli/README.md for the full command reference.

pnpm install -g @sra-srs/sra-cli

sra doctor                 # verify setup, credentials and provider keys
sra init                   # link this folder to an analysis
sra reverse                # or: generate a spec from the code already here
sra check --deep --suggest # trace requirements to source
sra push                   # publish traceability back to the platform

⚒️ Local Infrastructure & Testing Setup

SRA uses standard pnpm workspaces for monorepo management.

1. Initial Dependency Sync

# Install dependencies across all workspaces
pnpm install

2. Run Quality Gates (Pre-Commit Setup)

To configure local quality gating checks (which will run standard cleanups and monorepo linting automatically before every git commit):

# Install the pre-commit CLI framework
pip install pre-commit

# Install the git hooks defined in our .pre-commit-config.yaml
pre-commit install

# Optional: Run all quality checks manually against all files
pre-commit run --all-files

3. Run the Test Suites

The backend holds the unit/contract/E2E suite; the CLI has its own. Both run natively on ESM Jest.

pnpm test:backend   # backend unit, contract and E2E suites (MOCK_AI=true — no real model calls)
pnpm test:cli       # CLI suite
pnpm test:all       # both

4. Launch Local Development Services

# Initialize Identity & Data
pnpm run dev:backend

# Or run frontend and backend concurrently
pnpm run dev:all

🤖 Agentic & CI/CD Workflows

SRA leverages professional GitHub Actions for continuous quality assurance and codebase health:

• Pre-Commit Checks: Remote validation hook runner on push and Pull Requests targeting main/master.
• PR Labeler: Automatically tags incoming Pull Requests based on the modified files' directory pathways.
• Publish Docker: Automated image pushes to GHCR.
• Bundle Size: Continuous monitoring of Next.js JS payloads on every branch.
• Health Checks: Hourly automated uptime verification of the entire pipeline.
• Security Scans: Integrated CodeQL and dependency vulnerability checks.

---

📂 Project Structure

SRA/
├── .github/                # CI/CD Workflows (Lint, CodeQL, Stale)
├── .agent/                 # Agent workflows and skill definitions
├── backend/                # API Engine & Node.js orchestration workspace
│   ├── prisma/             # Schema & Migrations
│   ├── src/                # Services, controllers, and core AI logic
├── frontend/               # Next.js 16 Application workspace
│   ├── app/                # Server-driven App Router
│   ├── components/         # High-fidelity React components
├── cli/                    # SRA Toolkit npm workspace
├── terraform/              # Infrastructure as Code (Platform config)
├── docs/                   # Documentation & Security policies
└── package.json            # Root monorepo workspace definition

---

🗺️ Roadmap & Governance

• v2.0: Strategic 5-Layer Pipeline Implementation.
• v2.1: Interactive DFD Explorer & PNG Export.
• v2.2: GitHub CI/CD & Agentic Automation.
• v3.0: SWR Data Fetching & Backup Automation.
• v3.0: Enterprise Security Monitoring & Audit Logging.
• v3.1: Distributed Rate Limiting & Load Balancing.
• v3.2: Industry Benchmarking & MAS Refinement.
• v4.0: Full CLI Toolkit & Spec-to-Code Traceability.
• v4.1: Multi-Provider BYOK Architecture, SSE-based live pipeline/chat streaming, and a ChatGPT-style frontend rehaul (unified landing + product app).
• v4.5: Collaborative Real-time Multi-User Editing.
• v5.0: Custom Model Fine-tuning (MLOps integration).

Contributing

We welcome contributions from the community. Please review our Contribution Guidelines and Governance Policy for architectural context and coding standards.

Security Policy

To report vulnerabilities, please contact the security team via the repository's security advisory tab.

---

📄 License

This project is licensed under the Apache License 2.0. See the LICENSE file for the full legal text.