A Platform Orchestrator that provides opinionated, production-ready service templates to standardize architecture, improve developer velocity, and enforce platform governance through design.
Before diving in, let's clarify scope:
- NOT a deployment tool - ForgeWorks doesn't deploy your infrastructure. It provides templates and recommendations; actual provisioning is handled by your existing CI/CD (ArgoCD, GitHub Actions).
- NOT a replacement for Kubernetes - It's an orchestration layer that sits above your cluster, providing developer-facing workflows.
- NOT a full PaaS - It's a catalog + recommendation engine, not a Heroku-style managed platform.
ForgeWorks IS: An Internal Developer Platform (IDP) that standardizes service creation through ML-guided golden path templates and provides visibility into your service ecosystem.
ForgeWorks is an Internal Developer Platform (IDP) that acts as an orchestration layer between development teams and infrastructure tooling. It provides:
- Service Catalog - Central registry of all microservices with health status, ownership, and deployment metrics
- Golden Path Templates - Production-ready service blueprints with built-in CI/CD, monitoring, and best practices
- ML-Powered Recommendations - Intelligent template suggestions based on workload type, language, and requirements
- Anomaly Detection - Surface deployment patterns that indicate potential issues (high deploy frequency, consecutive rollbacks)
- Repository scaffolding - turbo.json, pnpm-workspace.yaml
- Monorepo setup - TurboRepo + PNPM workspace (package.json)
- Database schema & migrations - Alembic migrations
- Service Catalog API - CRUD endpoints
- Template API - Template routes
- ML Recommender - Rule-based engine
- Seed data - Demo seeder
- Mock adapters - GitHub, ArgoCD
- Anomaly API - Detection routes
- Metrics API - DORA metrics
- API docs - Auto-generated at
/docsendpoint - Versioning - Changesets config
- Unit tests - 159 tests (test suite)
- Auth backend - JWT security, Auth routes
# Backend API with Swagger docs
cd src/backend && uvicorn app.main:app --reload
# Visit http://localhost:8000/docs
# Frontend dashboard
cd src/frontend && pnpm dev
# Visit http://localhost:3000- Frontend Layers UI - Layer store, GlueBus
- Auth pages - Login, Register
- WebSocket - Real-time endpoint
- Auth frontend integration (token storage, protected routes)
- E2E tests with Playwright
- Docker Compose for one-command demo
- CI/CD pipeline (GitHub Actions)
┌─────────────────────────────────────────────────────────────────┐
│ EXPERIENCE LAYER │ Next.js Dashboard + ML Recommender │
├───────────────────────┼─────────────────────────────────────────┤
│ ML ORCHESTRATION │ Template Recommender + Anomaly Panel │
├───────────────────────┼─────────────────────────────────────────┤
│ API GLUE LAYER │ FastAPI + Adapters + State Store │
├───────────────────────┼─────────────────────────────────────────┤
│ TOOL APIS │ GitHub, ArgoCD, Prometheus, K8s │
└───────────────────────┴─────────────────────────────────────────┘
AGENTLESS - ALL API CONNECTIONS
| Principle | Description |
|---|---|
| Agentless | No agents deployed - all connectivity via REST APIs |
| Governance by Design | Standards encoded in templates, not policy documents |
| ML as Advisor | Recommendations to guide, not mandates to enforce |
| Golden Paths | Opinionated defaults that teams can extend |
| Layer | Technology |
|---|---|
| Backend | Python 3.11+ / FastAPI |
| Frontend | TypeScript / Next.js / Tailwind |
| Database | PostgreSQL |
| Cache | Redis |
| ML | scikit-learn |
| Container | Docker |
forge-works/
├── src/
│ ├── backend/ # FastAPI backend
│ │ ├── app/
│ │ │ ├── api/ # REST endpoints
│ │ │ ├── crud/ # Database operations
│ │ │ ├── db/ # Models & migrations
│ │ │ ├── schemas/ # Pydantic models
│ │ │ ├── adapters/ # External integrations
│ │ │ └── ml/ # ML components
│ │ ├── tests/
│ │ └── alembic/ # Database migrations
│ └── frontend/ # Next.js frontend
├── scripts/ # Development utilities
├── docs/ # Documentation
└── docker-compose.yml # Local development stack
The following endpoints are implemented and available in the current build.
| Method | Endpoint | Description |
|---|---|---|
| GET | / |
List services (pagination, filtering, search) |
| GET | /stats |
Service statistics for dashboard |
| GET | /{id} |
Get service by ID |
| GET | /slug/{slug} |
Get service by slug |
| POST | / |
Create new service |
| PUT | /{id} |
Update service |
| DELETE | /{id} |
Delete service |
| Method | Endpoint | Description |
|---|---|---|
| GET | / |
List templates (filter by workload/language) |
| GET | /{id} |
Get template details |
| GET | /slug/{slug} |
Get template by slug |
| POST | /recommend |
Get ML-powered template recommendations |
| Method | Endpoint | Description |
|---|---|---|
| GET | / |
List anomalies (filter by severity, type, status) |
| GET | /stats |
Anomaly statistics |
| GET | /{id} |
Get anomaly details |
| POST | / |
Create anomaly (from detection systems) |
| PATCH | /{id} |
Update anomaly |
| POST | /{id}/acknowledge |
Acknowledge anomaly |
| POST | /{id}/resolve |
Resolve anomaly |
| DELETE | /{id} |
Delete anomaly |
| Method | Endpoint | Description |
|---|---|---|
| GET | / |
Comprehensive metrics dashboard |
| GET | /dora |
DORA metrics only |
| GET | /health |
Service health metrics |
| GET | /deployment |
Deployment statistics |
| Method | Endpoint | Description |
|---|---|---|
| GET | /health |
Basic health check |
| GET | /health/detailed |
Component health status |
- Docker & Docker Compose
- Python 3.11+
- Node.js 18+ (for frontend)
# Clone the repository
git clone https://github.com/adamatdevops/forge-works.git
cd forge-works
# Start infrastructure (PostgreSQL, Redis)
docker-compose up -d
# Backend setup
cd src/backend
python -m venv venv
source venv/bin/activate
pip install -e ".[dev]"
# Run migrations
alembic upgrade head
# Seed demo data
python -m app.db.seed
# Start the API server
uvicorn app.main:app --reloadAPI documentation available at http://localhost:8000/docs
# Frontend setup (new terminal)
cd src/frontend
pnpm install
pnpm devFrontend available at http://localhost:3000
See LOCAL_DEV.md for detailed setup instructions.
A Figma-inspired composable UI built with:
- Layer Panel - Toggle visibility and reorder dashboard layers
- GlueBus - Pub/sub pattern for cross-layer communication
- Service Catalog Layer - Grid view with health indicators
- Templates Layer - ML-powered recommendation interface
- Pipelines Layer - CI/CD status with real-time updates
- Anomalies Layer - Deployment pattern alerts
Central registry showing all services with:
- Health status (healthy, degraded, unhealthy)
- Ownership (team assignment)
- Deployment metrics (deploys today, rollbacks this week)
- Links to documentation, dashboards, runbooks
Pre-configured service blueprints including:
- Python API - FastAPI + PostgreSQL + async
- Go Microservice - High-performance services
- Stream Processor - Kafka + event-driven
- Data Pipeline - Batch processing workflows
- ML Service - Model serving infrastructure
Each template is designed to include CI/CD pipelines, monitoring, tests, and documentation as part of the Golden Path standard.
Intelligent matching based on:
- Workload type (api, batch, stream, ml)
- Programming language preference
- Capability requirements
- Team usage patterns (future)
Surfaces potential issues:
- High deploy frequency (>5 deploys/day)
- Consecutive rollbacks
- Pipeline failures
- Health degradation patterns
This repository is the implementation surface of an Internal Developer Platform concept:
- The focus is on demonstrating platform engineering thinking, governance-through-design, and ML-assisted guidance
- Architecture decisions and planning artifacts guide all implementation choices
- This is a portfolio demonstration, not a simulation of a full enterprise deployment
The codebase showcases real patterns used in production IDPs while remaining appropriately scoped for evaluation.
MIT
Built as a portfolio demonstration of Internal Developer Platform concepts and Platform Engineering practices.