Production-readiness analysis platform that analyzes engineering artifacts (OpenAPI specs, architecture diagrams, documentation) to identify potential issues before deployment. Uses a hybrid approach combining rule-based heuristics with AI-powered synthesis to generate comprehensive analysis reports.
- 🔍 Multi-Format Analysis - Supports OpenAPI (JSON/YAML), architecture diagrams, and Markdown documentation
- 🤖 AI-Powered Insights - Synthesizes heuristic findings with contextual analysis using multiple LLM providers
- ⚡ Fast Results - Content hash-based caching for instant results on duplicate analyses
- 📊 Comprehensive Reports - Production readiness scores, prioritized findings, charts, and actionable remediation steps
- 🎯 Confidence-Based Analysis - Distinguishes between high/medium/low confidence findings for accurate risk assessment
- 🔒 Structured Output - Guaranteed schema compliance through Pydantic AI validation
- Docker and Docker Compose
- Python 3.12+ (for local development)
- Bun (for frontend development)
# Clone the repository
git clone https://github.com/your-org/faultline.ai.git
cd faultline.ai
# Setup env
make env-setup
# Or manually create .env files in server and client directories
# Start all services
docker-compose up
# Access the application
# Frontend: http://localhost:3000
# Backend API: http://localhost:8080
# API Docs: http://localhost:8080/docsBackend:
cd server
uv sync
uv run fastapi dev app/main.pyFrontend:
cd client
bun install
bun devFaultline.ai consists of three main components:
- Frontend - Next.js 16 (React 19, TypeScript) with App Router
- Backend - FastAPI (Python 3.12) with async processing
- AI System - Pydantic AI with support for OpenAI, Google, Groq, and Ollama
- Cache/State - Redis for job state management and result caching
See Architecture Documentation for detailed system architecture.
Comprehensive documentation is available in the /docs directory:
- Architecture (ARCH.md) - System architecture, component overview, data flow, and deployment architecture
- Frontend (FRONTEND.md) - Frontend technology stack, routing, state management, UI components, and build process
- Backend (BACKEND.md) - Backend API routes, business logic, data models, Redis integration, and AI integration
- AI System (AI.md) - AI provider support, model configuration, system prompts, input/output structures, and cost considerations
- Redis (REDIS.md) - Redis connection management, key patterns, data flow, operations, TTL management, and performance considerations
- Deployment (DEPLOYMENT.md) - High request volume handling, AWS deployment strategy, CI/CD pipeline, and environment separation
- Framework: Next.js 16.0.10 (App Router)
- Runtime: React 19.2.1
- Language: TypeScript 5
- Styling: Tailwind CSS 4
- State Management: Zustand
- UI Components: Radix UI
- Charts: Recharts
- Package Manager: Bun
- Framework: FastAPI 0.112.1+
- Language: Python 3.12+
- AI Integration: Pydantic AI 1.35.0+
- Cache/State: Redis 7.1.0+
- Logging: Loguru
- Package Manager: UV
- OpenAI (GPT models)
- Google (Gemini)
- Groq
- Ollama (local models)
faultline.ai/
├── client/ # Next.js frontend
│ ├── app/ # App Router pages and routes
│ ├── components/ # UI components
│ └── lib/ # Utilities, API client, hooks
├── server/ # FastAPI backend
│ ├── app/
│ │ ├── routers/ # API route handlers
│ │ ├── logic/ # Business logic
│ │ ├── schemas/ # Pydantic models
│ │ └── main.py # FastAPI app entry point
│ └── Dockerfile
├── docs/ # Documentation
│ ├── ARCH.md
│ ├── FRONTEND.md
│ ├── BACKEND.md
│ ├── AI.md
│ ├── REDIS.md
│ └── DEPLOYMENT.md
└── docker-compose.yaml # Local development setup
POST /artifacts/analyze- Submit artifact for analysisGET /jobs/{job_id}- Get job statusGET /jobs/{job_id}/result- Get analysis resultGET /jobs- List all jobs
GET /health- Health checkGET /- API root
See Backend Documentation for detailed API documentation.
Backend:
REDIS_URL- Redis connection stringAI_PROVIDER- openai|google|groq|ollamaAI_MODEL- Model identifierOPENAI_API_KEY- OpenAI API keyGEMINI_API_KEY- Google API keyGROQ_API_KEY- Groq API keyOLLAMA_BASE_URL- Ollama server URLDEMO_MODE- Enable demo mode (bypasses AI)MAX_CONTENT_SIZE- Max artifact size (default: 500KB)LOG_LEVEL- Logging level
Frontend:
BACKEND_API_URL- Backend API URLNODE_ENV- Environment mode
See Backend Documentation for complete configuration options.
- User submits artifact (OpenAPI, architecture diagram, or documentation)
- Content is normalized into structured data (endpoints, components, sections)
- Heuristics run to identify rule-based findings with confidence levels
- AI synthesizes findings into prioritized analysis with contextual insights
- Results are cached by content hash for instant retrieval on duplicates
- Report generated with production readiness score, findings, charts, and next steps
Production-readiness analysis requires more than simple pattern matching. While rule-based heuristics can identify specific issues, they cannot:
- Prioritize findings by real-world impact - A missing authentication on a read-only endpoint is less critical than on a write endpoint
- Synthesize contextual insights - Multiple low-severity findings in the same area may indicate a systemic problem
- Generate actionable remediation - Context-aware remediation strategies that consider specific architecture and constraints
- Create executive summaries - Clear, concise explanations of what will break first and why
- Calculate production readiness scores - Understanding relative importance of issues, their interactions, and overall system health
- Identify implicit risks - Risks implied by the combination of findings rather than explicitly stated
Faultline.ai uses a two-stage hybrid approach:
- Heuristics (Rule-Based) - Fast, deterministic, high-confidence findings with confidence levels
- AI Synthesis - Contextual analysis, prioritization, and insight generation
This combines the reliability of rules with the intelligence of AI, resulting in accurate and insightful analysis.
Faultline.ai employs multiple layers of safety to minimize AI hallucinations:
- Structured Input Grounding - AI operates on normalized, structured data (not raw text) with pre-validated heuristic findings
- Strict Interpretation Rules - High-confidence findings treated as factual; low-confidence as weak signals
- Confidence-Based Weighting - Distinguishes between high/medium/low confidence to prevent overemphasizing uncertain findings
- Explicit Prohibition of Invention - AI cannot invent technologies, services, or failures not present in the artifact
- Two-Stage Validation - Heuristics validate input before AI processing
- Low Temperature Setting -
temperature=0.2reduces creativity and increases consistency - Structured Output Validation - Pydantic AI enforces schema compliance with automatic retries
The system guarantees structured output through multiple mechanisms:
- Pydantic AI Framework - Enforces structured output at the framework level with automatic schema validation
- Pydantic Schema Definition - Exact structure defined with type enforcement (e.g.,
production_readiness_scoremust be int) - Nested Model Validation - Even nested structures (findings, charts) are validated
- Strict System Prompt - Explicit output format requirements in the AI prompt
- Retry Logic - Up to 3 agent retries + 3 output retries for schema compliance
- Runtime Type Validation - Additional checks after Pydantic AI validation
- Explicit Field Requirements - Prompt specifies exact requirements (e.g., "exactly three charts")
This multi-layered approach ensures reliable, actionable analysis reports with guaranteed schema compliance.
# Backend tests
cd server
uv run pytest
# Frontend tests
cd client
bun test# Backend linting
cd server
uv run isort .
uv run ruff check .
# Frontend linting
cd client
bun run lintFaultline.ai is designed for containerized deployment on AWS:
- Frontend: S3 + CloudFront (static) or ECS Fargate
- Backend: ECS Fargate with auto-scaling
- Redis: ElastiCache
- Load Balancing: Application Load Balancer
See Deployment Documentation for complete deployment strategy, CI/CD pipeline, and environment separation.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add some amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
Rule-based heuristics can identify specific issues but cannot prioritize findings by real-world impact, synthesize contextual insights, generate actionable remediation, or create executive summaries. The hybrid approach combines the reliability of rules with the intelligence of AI.
Multiple safeguards are in place:
- AI operates only on structured, validated data (normalized artifacts + heuristic findings)
- Strict interpretation rules treat high-confidence findings as factual
- Explicit prohibition against inventing technologies or services
- Low temperature setting (0.2) reduces creativity
- Pydantic AI enforces schema compliance with automatic retries
The system automatically retries up to 3 times for agent calls and 3 additional times for schema validation (total: up to 9 attempts). Invalid outputs are rejected and the model is retried until a valid schema-compliant response is generated.
Content is hashed using SHA256. If the same content is analyzed again within 24 hours, the cached result is returned instantly without AI processing, significantly reducing costs and improving response time.
Yes! Faultline.ai supports multiple providers:
- OpenAI (GPT models)
- Google (Gemini)
- Groq
- Ollama (local models)
Configure via the AI_PROVIDER environment variable.
- Heuristic findings are rule-based, deterministic, and have confidence levels (high/medium/low)
- AI findings synthesize heuristic findings, add contextual insights, and prioritize by production risk
High-confidence heuristic findings are treated as factual by the AI.
The score (0-100) is calculated by the AI based on:
- Severity and quantity of findings
- Category distribution (security, reliability, etc.)
- Real-world production risk assessment
It's a relative indicator meant to help prioritize remediation efforts, not an absolute measure.
Yes. The system processes artifacts locally. For maximum privacy, use Ollama with local models - no data leaves your infrastructure.
- OpenAPI/Swagger: JSON and YAML
- Architecture diagrams: Markdown text descriptions
- Documentation: Markdown files
- Cached results: Instant (< 1 second)
- New analysis: 5-30 seconds depending on:
- Artifact size
- AI provider (Groq is fastest, Ollama slowest)
- Model complexity
Currently no rate limiting in the open-source version. For production deployments, see Deployment Documentation for recommended rate limiting strategies.
- Fork the repository
- Create a feature branch
- Make your changes
- Submit a pull request
See the Contributing section above.
See LICENSE file for details.
