Tagline: AI-Powered Engineering Review & Code Intelligence Platform Mission: Foundry acts like an experienced Staff Engineer that understands entire codebases, reasoning globally to deliver architectural insights, security reviews, FinOps metrics, and dependency upgrade maps.
License: AGPL-3.0-or-later with commercial licensing available for organizations that require proprietary deployment terms. See LICENSE, CONTRIBUTING.md, and SECURITY.md.
Foundry is designed around an AI-First, Modular, and Provider-Agnostic architectural model. It separates rapid-response API requests from resource-intensive background AST analysis and agent reasoning workflows.
graph TD
%% Clients
User[Developer / Engineer] -->|HTTPS / WSS| Web[Next.js Frontend]
Web -->|Next.js Server Side| API[ASP.NET Core 10 API Gateway]
%% API Services
API -->|Reads / Writes| Postgres[(PostgreSQL DB)]
API -->|Session / Rate Limits| Redis[(Redis Cache & Event Bus)]
API -->|Enqueues Job| Queue[Redis BullMQ / Outbox Queue]
%% Background Workers
Queue -->|Dequeues Job| Worker[ASP.NET Core 10 Background Worker]
Worker -->|Read Code & Walk AST| Parser[Repository Parser & AST Analyzer]
Worker -->|Triggers Scanning Engines| Security[Security, Dependency, Cost & Infra Analyzers]
Worker -->|Fetch RAG Context| VectorDB[(pgvector DB / Vector Store)]
%% AI Orchestration
Worker -->|Sends Intent & Prompts| Planner[Planning & Recommendation Engine]
Planner -->|OpenAI, Anthropic, Gemini| Gateway[Model Gateway / Proxy]
Gateway -->|LLM Requests| LLM[Model Provider API]
%% Observability
API & Worker -->|Metrics / Traces| Otel[OpenTelemetry / OTLP Collector]
Otel -->|Data Visualization| Grafana[Grafana / Prometheus / Jaeger]
The Foundry platform is organized as a unified monorepo to ensure tight integration of shared types, schemas, and pipeline files while maintaining clean microservice boundaries.
foundry/
├── .github/
│ └── workflows/
│ └── ci.yml # CI Pipeline (dotnet test + npm lint/build)
├── apps/
│ └── foundry-web/ # Next.js Frontend (React, TypeScript, TailwindCSS, shadcn/ui)
│ ├── src/
│ │ ├── app/ # Next.js App Router Pages (Dashboards, Chat, Settings)
│ │ ├── components/ # UI components (Graphs, charts, widgets)
│ │ └── lib/ # Shared client hooks and API wrappers
│ ├── Dockerfile # Next.js Standalone Runner Dockerfile
│ └── package.json
├── packages/
│ └── Foundry.Shared/ # Shared domain models, contracts, and interfaces (NuGet)
│ ├── Data/ # EF Core Database Context mappings
│ ├── Implementations/ # Pluggable Mock implementations (MockServiceStubs)
│ ├── Interfaces/ # System analyzer & LLM interfaces
│ └── Models/ # Domain entities (RepositoryInfo, AnalysisJob, ScanResult)
├── services/
│ ├── Foundry.Api/ # API Gateway Microservice (ASP.NET Core 10 Web API)
│ │ ├── Controllers/ # REST API Controllers (Workspace, Analysis, Chat)
│ │ ├── Program.cs # Main entry point, Dependency Injection config
│ │ └── Dockerfile # ASP.NET Api runner Dockerfile
│ └── Foundry.Worker/ # Background Worker Microservice (ASP.NET Core 10 Worker Service)
│ ├── Jobs/ # Background Queue Worker (AnalysisQueueWorker)
│ ├── Program.cs # Main worker entry point
│ └── Dockerfile # ASP.NET Worker runner Dockerfile
├── infra/
│ └── terraform/ # Cloud Infrastructure (AWS configurations)
│ ├── main.tf # VPC, RDS (PostgreSQL), ElastiCache (Redis), ECS Cluster configuration
│ ├── variables.tf # Deployment variable definitions
│ └── providers.tf # Terraform provider block
├── docker-compose.yml # Local multi-container development environment Orchestrator
├── Directory.Build.props # Global C# Compiler Settings (warnings, C# 13, nullable checks)
├── Foundry.slnx # C# Solution workspace file
└── README.md # Core architecture design and documentation
The platform is split into three decoupled services:
- Foundry.Api:
- Boundary: HTTP edge. Does not perform heavy calculations or raw code cloning.
- Responsibilities: User authentication, API gateway routing, telemetry emission, repo registration metadata, and real-time streaming chat completions.
- Foundry.Worker:
- Boundary: Background message consumers. Runs within isolated security profiles.
- Responsibilities: Git repository cloning, AST generation, semantic indexing/vectorization, dependency resolving, and AI planner orchestrations.
- Model Gateway:
- Boundary: Outbound LLM Proxy layer (provider-agnostic).
- Responsibilities: API key management, request routing (OpenAI, Anthropic, Gemini), semantic rate-limiting, request caching, and token budgeting.
Below is the production-ready SQL database schema defining workspaces, scanning runs, explainable findings, and multi-tenant mapping:
-- Enable UUID extension
CREATE EXTENSION IF NOT EXISTS "uuid-ossp";
-- 1. Repositories (Workspace Metadata)
CREATE TABLE repositories (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
tenant_id VARCHAR(100) NOT NULL,
name VARCHAR(255) NOT NULL,
git_url VARCHAR(1024),
default_branch VARCHAR(100) DEFAULT 'main',
zip_storage_path VARCHAR(1024),
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP NOT NULL
);
-- Index for tenant separation
CREATE INDEX idx_repositories_tenant ON repositories(tenant_id);
-- 2. Analysis Jobs (Execution Tasks)
CREATE TYPE job_status AS ENUM (
'Queued', 'Cloning', 'Parsing', 'Analyzing', 'GeneratingRoadmap', 'Completed', 'Failed'
);
CREATE TABLE analysis_jobs (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
repository_id UUID NOT NULL REFERENCES repositories(id) ON DELETE CASCADE,
tenant_id VARCHAR(100) NOT NULL,
triggered_by_user_id VARCHAR(100) NOT NULL,
status job_status DEFAULT 'Queued' NOT NULL,
error_message TEXT,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP NOT NULL,
started_at TIMESTAMP WITH TIME ZONE,
completed_at TIMESTAMP WITH TIME ZONE
);
CREATE INDEX idx_analysis_jobs_tenant ON analysis_jobs(tenant_id);
CREATE INDEX idx_analysis_jobs_status ON analysis_jobs(status);
-- 3. Scan Results (Explainable Findings)
CREATE TYPE finding_category AS ENUM (
'Security', 'Architecture', 'Dependency', 'Infrastructure', 'FinOps', 'CodeQuality', 'Upgrade'
);
CREATE TYPE finding_priority AS ENUM (
'Critical', 'High', 'Medium', 'Low', 'Info'
);
CREATE TABLE scan_results (
id UUID PRIMARY KEY DEFAULT uuid_generate_v4(),
job_id UUID NOT NULL REFERENCES analysis_jobs(id) ON DELETE CASCADE,
tenant_id VARCHAR(100) NOT NULL,
category finding_category NOT NULL,
priority finding_priority NOT NULL,
rule_id VARCHAR(255) NOT NULL,
title VARCHAR(512) NOT NULL,
file_path VARCHAR(1024),
line_start INT,
line_end INT,
-- Explainable context (Core Principle #5)
why TEXT NOT NULL,
impact TEXT NOT NULL,
evidence TEXT NOT NULL,
fix_action TEXT NOT NULL,
estimated_effort VARCHAR(100) NOT NULL,
additional_metadata_json JSONB,
created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP NOT NULL
);
CREATE INDEX idx_scan_results_tenant ON scan_results(tenant_id);
CREATE INDEX idx_scan_results_category ON scan_results(category);
CREATE INDEX idx_scan_results_priority ON scan_results(priority);
CREATE INDEX idx_scan_results_job ON scan_results(job_id);All endpoints consume and produce JSON. Authentication is required via OAuth2/OIDC JWT tokens.
GET /api/workspaces:- Headers:
X-Tenant-Id: <tenant-uuid> - Response:
200 OKList<RepositoryInfo>
- Headers:
POST /api/workspaces:- Request:
{"name": "string", "gitUrl": "string", "defaultBranch": "string"} - Response:
201 CreatedRepositoryInfo
- Request:
POST /api/analysis/jobs:- Request:
{"repositoryId": "uuid"} - Response:
202 AcceptedAnalysisJob
- Request:
GET /api/analysis/jobs/{jobId}:- Response:
200 OKAnalysisJob
- Response:
GET /api/analysis/jobs/{jobId}/findings:- Response:
200 OKList<ScanResult>
- Response:
GET /api/analysis/jobs/{jobId}/roadmap:- Response:
200 OKEngineeringRoadmapDto
- Response:
POST /api/chat/ask:- Request:
{"repositoryId": "uuid", "question": "string", "fileFilters": ["string"]} - Response:
200 OK{"answer": "string"}
- Request:
POST /api/chat/stream:- Request:
{"repositoryId": "uuid", "history": [{"role": "user", "content": "string"}]} - Response:
Chunked Text stream (WSS/SSE)
- Request:
The background processing cycle flows sequentially to guarantee maximum context gathering before model evaluation:
[Job Queued] ──> [Clone Repo] ──> [Extract AST Structure] ──> [Ingest Vector Embeddings (RAG)]
│
└──> [Parallel Scanning: Security, Dependency, Cost, Infra, Upgrade Advisor]
│
└──> [Planner & Recommendation Engine] ──> [Generate Roadmap] ──> [Complete]
- AST Parser: Extracts syntax trees, functional references, and project structure (avoiding line-by-line file uploads to LLMs).
- RAG Embedding Ingestion: Populates vector database (
pgvector/qdrant) with file chunks and tokenized methods. - Static Scanner Audits: Scans manifest files, secrets patterns, Terraform configurations, Docker configs, and pipelines.
- LLM Orchestration: The Planning Engine analyzes the overall scope, drafts structured prompts combining AST analysis and scanner findings, queries the Model Gateway, and feeds outcomes to the Recommendation Engine for prioritization.
- Authentication: Offloaded to standard enterprise Identity Providers (e.g. Keycloak, Auth0, Entra ID) using OpenID Connect (OIDC).
- Authorization: Role-Based Access Control (RBAC) mapping system access (e.g.
PlatformAdmin,WorkspaceWriter,SecurityAuditor). - Multi-Tenant Isolation:
- Every SQL table includes a mandatory
tenant_idfield. - EF Core utilizes a Global Query Filter (
HasQueryFilter(e => e.TenantId == _currentTenantProvider.Id)) so developers can never query records belonging to another tenant by accident. - In background jobs, cloned repository workspaces are deleted immediately upon job completion to limit static file liability.
- Every SQL table includes a mandatory
To ensure sub-second response times for dashboards and interactive code chat:
- Dashboard Cache: Scan results and generated roadmaps are cached in Redis with an absolute expiration linked to the Analysis Job lifespan.
- LLM Response Caching: Semantic caching maps embedding similarity of incoming chat queries to previous answers. If a prompt query has
>97%cosine similarity to an active cached result, the system returns the cached answer, saving API cost. - Workspace File Cache: Cloned git files are cached for up to 30 minutes in the worker's workspace to handle consecutive runs or instant chat context without re-cloning.
sequenceDiagram
autonumber
actor Dev as Developer
participant Web as Next.js Web
participant API as Api Gateway
participant DB as PostgreSQL
participant Cache as Redis Queue
participant Worker as Background Worker
participant LLM as Model Gateway
Dev->>Web: Register & Scan Repository
Web->>API: POST /api/analysis/jobs
API->>DB: Write Job record (Queued status)
API->>Cache: Publish Job Queued Event
API-->>Web: 202 Accepted (Job ID)
activate Worker
Cache->>Worker: Dequeue Job
Worker->>DB: Update Status to Cloning
Worker->>Worker: Clone repository to Sandbox
Worker->>Worker: Parse AST structure & chunk files
Worker->>DB: Save chunks & AST mapping
Worker->>DB: Update Status to Analyzing
rect rgb(200, 220, 240)
note right of Worker: Run Parallel Scanners
Worker->>Worker: Scan Security & Secrets
Worker->>Worker: Scan Dependency Graph & Costs
Worker->>Worker: Scan IaC & Docker configs
end
Worker->>DB: Write Scanner Findings (ScanResult rows)
Worker->>DB: Update Status to GeneratingRoadmap
Worker->>LLM: Send Findings + AST Context (Prompt)
LLM-->>Worker: Return prioritised roadmap steps
Worker->>DB: Save Roadmap Details
Worker->>DB: Update Status to Completed
deactivate Worker
Web->>API: GET /api/analysis/jobs/{id}/roadmap
API->>DB: Fetch completed roadmap
API-->>Web: 200 OK (Render Engineering Roadmap)
Foundry will be engineered in four distinct phases:
- Monorepo structure setup, ASP.NET 10 solution, Next.js framework bootstrap.
- Docker containerization configurations for local development orchestration.
- Integration tests scaffolding, GitHub Actions CI pipelines, and Terraform workspace declarations.
- Active repository parsing (AST generator + local repository sandbox).
- Integration of pattern-based scanning scripts (Semgrep/Trivy wrappers for Security, OpenTrivy for dependencies).
- Single-provider model integration (OpenAI API connection).
- Basic Dashboard showing simple table metrics and file list warnings.
- Provider-agnostic Model Gateway (Anthropic, Gemini, local Ollama integrations).
- Vector indexing database integrations (PGVector) to support full codebase RAG context.
- Implementation of the Planning Engine to dynamically guide LLM review loops based on repository profiles.
- interactive UI Chat page allowing natural language exploration of active repositories.
- Strict Multi-Tenancy isolation with Tenant-specific encryption keys.
- Real-time WebSockets update channel showing live scanner parsing status.
- Integration of FinOps (cloud pricing catalog lookup) and Migration Advisor simulations.
- Premium PDF report generator outputting executive summaries.
Before a production deployment, disable Database:AutoInitialize, provision the
database through a reviewed migration job, configure OIDC authentication,
and set an explicit Cors:AllowedOrigins list. The development headers
X-Tenant-Id and X-User-Id are only a local-development compatibility path;
production identity must derive these values from verified claims.
To maintain high code quality across the platform:
- Naming Conventions: Use
PascalCasefor classes, interfaces (IInterface), and methods;camelCasefor local variables and arguments;_camelCasefor private fields. - Language Level: C# 13, targeting .NET 10 runtime.
- Nullable Context: Must be set to
enableglobally. Check for null parameters and throw appropriate exceptions. - Dependency Injection: Utilize constructor injection throughout. Register services in
Program.csunder the correct lifetime scope.
- Naming Conventions: Use
kebab-casefor file directories;PascalCasefor React components;camelCasefor functions and hooks. - Routing: Utilize Next.js App Router folders inside
src/app. - Styling: Utilize Tailwind CSS classes. Limit raw inline CSS.
- State Management: Utilize Server Components for initial rendering and standard React Context / state hooks for user-facing interactive elements.
Foundry supports two execution modes for local development:
Create local runtime configuration first:
cp .env.example .envSet OPENAI_API_KEY and OPENAI_MODEL_NAME for real model responses, embeddings,
and web-backed investigations; leaving either blank disables AI features rather
than returning mock data. Set GIT_ACCESS_TOKEN only when cloning private
GitHub repositories over HTTPS. NEXT_PUBLIC_API_URL is embedded when the web
image is built, so rebuild that image after changing the URL. Set
OTEL_EXPORTER_OTLP_ENDPOINT only when an OTLP/gRPC collector is available.
Never commit .env.
To spin up all services (PostgreSQL, Redis, API, Worker, and Next.js) in the background:
docker compose up --build -dAccess the services at:
- Frontend Dashboard:
http://localhost:3000 - Backend API Gateway:
http://localhost:8080 - API liveness:
http://localhost:8080/health/live - API readiness:
http://localhost:8080/health/ready
PostgreSQL, Redis, and application ports bind to 127.0.0.1 by default. Change
the port variables in .env when the defaults conflict; use a reviewed Compose
override if another host must access them.
To run the database dependencies in Docker and the application processes natively on your host machine via CLI:
- On Windows (PowerShell):
./dev.ps1 - On Linux/macOS (Bash):
chmod +x dev.sh ./dev.sh
This script will boot PostgreSQL and Redis inside Docker, spin up the API and Worker background C# processes, and start the Next.js development server.
It validates prerequisites and configuration, waits for dependencies and API
health, and stops the native application processes on exit. Database containers
are left running for reuse by default. Use ./dev.ps1 -StopDependencies or
./dev.sh --stop-dependencies to stop them when the script exits.