Forge Ai Platform

Forge — an AI-Native Internal Application Platform

> An internal PaaS where engineers ship code and everyone else builds apps with AI — on one governed foundation. > System design + reference implementation of the control plane (Spring Boot · Kubernetes · GitOps · AI agents).

---

The idea in one paragraph

Most companies have the same problem: engineers rebuild login, data access and deployment plumbing for every internal tool, business teams wait months on IT for simple apps, and AI-generated ("vibe-coded") apps have nowhere safe to run. Forge is an internal, Vercel-like platform that solves all three at once. It gives two build paths — Path A (describe an app to an AI agent) and Path B (push your own code) — that converge into one pipeline: Validate → Deploy → Publish → Live, running on one governed foundation: SSO, RBAC, secrets vault, audited data access, app catalog and observability. It is designed to be the only place an employee can use AI on real company data, safely — and because it's the official path, what they build gets supported, secured and kept.

What problems it solves

| Pain today | How the platform fixes it — by design | |---|---| | Nobody tracks internal apps — who built what, who can see what | One catalog + audit trail: every app, every permission, visible | | Engineers rebuild login, data & secrets on every project | Built-in foundation: SSO, data access & secrets are platform primitives | | Every team rebuilds the same components | Component marketplace: assemble from reusable skills, connectors, MCPs — don't rebuild | | "I vibe-coded an app — now how do I deploy it?" | One-instruction deploy: the platform handles build, hosting, TLS, domain | | "How do I connect to company data?" | Governed connector broker: AI wires scoped, audited data access for you | | Simple tools wait months on engineering | Self-service in minutes: business builds; engineers do the genuinely hard parts |

High-level design

Two planes inside the corporate trust boundary (VPN + SSO). The Gateway is the only path to company data — for humans, apps, and AI agents alike.

flowchart TB
    subgraph TB1["Internal trust boundary — VPN + SSO"]
        direction TB
        subgraph CP["BUILD & MANAGE — control plane"]
            UI["App Management UIcreate · upload · deploy · logs"]
            CHAT["AI Chat & Coding UIdescribe · generate · fix"]
            API["Control APIeverything-as-API"]
            DE["Deployment Enginebuild → deploy → rollback"]
            ORCH["AI Orchestratorgenerator · Guardian · fix"]
        end
        subgraph RT["RUN & SERVE — runtime + data"]
            GW["Gatewayidentity · routing · RBAC · audit"]
            APPS["Running appscontainers on Kubernetes"]
            BROKER["Connector Brokergoverned · RBAC-scoped"]
            DATA[("Company & external data")]
        end
    end
    USERS(("Users")) --> UI
    USERS --> CHAT
    USERS --> GW
    UI --> API
    CHAT --> API
    API --> DE
    API --> ORCH
    DE --> APPS
    GW --> APPS
    APPS --> BROKER
    BROKER --> DATA

Two paths, one destination

flowchart LR
    subgraph A["Path A — AI (no-code)"]
        A1[Describe] --> A2[Generate] --> A3[Connect scoped data]
    end
    subgraph B["Path B — Code (pro-code)"]
        B1[Write code] --> B2[Git push / upload] --> B3[Build image]
    end
    A3 --> V{{"Validate — Guardian agentsecurity · permissions · policy"}}
    B3 --> V
    V --> D[Deploy] --> P["PublishURL + TLS + SSO"] --> L(("Live"))

Both paths land on the same runtime, data layer, governance and catalog. An AI-built app can never reach data its creator couldn't reach — permissions are enforced server-side, not by the model.

The layered foundation (built bottom-up)

The platform is a deployment engine first; AI is the top layer — a consumer of clean platform primitives, not a bolt-on.

| # | Layer | Responsibility | |---|---|---| | 7 | AI / agentic layer | Generator · Guardian · auto-fix · self-heal — drives layers 1–6 | | 6 | Connector broker & component registry | Governed data path + reusable, machine-readable blocks | | 5 | Platform client SDK | Keyless platform.db / data / identity / files / ai | | 4 | Gateway | Identity · routing · RBAC · audit — one front door, also governs app-to-app | | 3 | Deployment engine — the kernel | Build → deploy → records → rollback | | 2 | Control-plane API | Everything-as-API — no UI-only capability | | 1 | Domain model & metadata DB | Apps · envs · deployments · builds · resources · secrets · permissions · audit |

Six disciplines applied from day one to make the substrate AI-ready: everything-as-API · structured error codes · declarative app state · machine-readable building blocks (MCP) · event timeline as data · server-enforced RBAC.

The deployment engine

API-driven pipeline: trigger → queue → worker. Every step writes records and streams logs; failures route to AI auto-fix.

flowchart LR
    T["1 · TriggerAPI: deploy"] --> Q["2 · EnqueueRedis queue"] --> W["3 · Worker"]
    W --> B["4 · BuildBuildKit → image → registry"]
    B --> G["5 · ValidateGuardian scan"]
    G --> M["6 · Manifest → Gitdesired state"]
    M --> R["7 · GitOps reconcileArgo CD applies"]
    R --> RO["8 · Rolling update"] --> H["9 · Health gate"]
    H --> P["10 · PublishIngress + TLS + DNS"] --> L["11 · Livemark is_current"]
    B -. on failure .-> FIX["AI auto-fixstructured error → sandbox → patch → re-run"]
    FIX -.-> B
    L -. "rollback = flip is_current — instant, no rebuild" .-> M

Build — isolated Kubernetes Jobs run rootless BuildKit; Cloud Native Buildpacks auto-detect the stack (Python/Node/Go/…) or a Dockerfile is used; layer caching keeps rebuilds fast; images are scanned (Trivy + Guardian) and pushed to the registry as app:deploy-N.

Deploy — the control plane writes a declarative manifest (Deployment + Service + Ingress) to Git; Argo CD reconciles the cluster to match. Rolling updates give zero downtime; rollback is flipping is_current to the prior deployment record — no rebuild, instant.

Run — request → wildcard DNS (*.apps.internal) → Ingress → Service → Pods. One namespace per app for isolation. HPA/KEDA scale pods (scale-to-zero for idle apps); Karpenter scales nodes. Pure-static apps are served from object storage + CDN, bypassing the cluster entirely.

App-to-app rule — apps call each other's APIs via the gateway, never each other's database. Shared data goes through the broker as a registered resource. Every call is identity-checked and audited.

The AI / agentic layer

A single platform agent orchestrates specialized sub-agents across the whole app lifecycle, calling the same platform APIs a human would — inside the user's RBAC, with sensitive actions gated by human approval (HITL).

flowchart TB
    O["Agent Orchestratorplans · routes · merges results"]
    O --> GEN["GeneratorNL → app"]
    O --> GUARD["Guardianvalidate"]
    O --> FIX["Fix agentauto-fix on failure"]
    O --> HEAL["Self-heal agent"]
    GEN --> MCP["MCP tool gateway + policyblocks unauthorized actions · user-scoped RBAC"]
    GUARD --> MCP
    FIX --> MCP
    HEAL --> MCP
    MCP --> PRIM["Platform primitives:Control API · structured errors · component registry · governed broker"]

| Lifecycle stage | What the agent does | Tools it calls | |---|---|---| | Generate | Prompt → working app; wires data & reuses existing components | generate_app · broker.data · registry | | Build | Detect stack, build image, fix on failure | build · use_skill | | Validate | Guardian: security, permission & policy scan | guardian_scan · Trivy · Semgrep | | Deploy | Write manifest, roll out, roll back | deploy · rollback | | Run & heal | Watch apps; restart / recover / rollback | health_watch · restart | | Reuse | Discover & assemble existing blocks | registry.search · MCP connectors | | Observe | Answer "why is it slow?" in plain language | logs.query · metrics |

Capabilities ship up a maturity ladder: 1 Validate → 2 Auto-fix → 3 Authoring → 4 Observability Q&A → 5 Self-heal → 6 Multi-agent reuse.

Data model (platform metadata only)

The platform stores metadata only — business data stays in the connected sources, reached through the broker.

erDiagram
    APPS ||--o{ ENVIRONMENTS : has
    APPS ||--o{ DEPLOYMENTS : has
    ENVIRONMENTS ||--o{ DEPLOYMENTS : targets
    DEPLOYMENTS ||--o{ BUILDS : produces
    APPS ||--o{ APP_RESOURCES : links
    DATA_RESOURCES ||--o{ APP_RESOURCES : "granted to"
    ENVIRONMENTS ||--o{ SECRETS : scopes
    APPS {
        uuid id PK
        string slug
        string build_type "low_code | code_deployed | hybrid"
        string lifecycle
    }
    DEPLOYMENTS {
        uuid id PK
        string commit_sha
        string status
        boolean is_current "rollback flips this"
    }
    BUILDS {
        uuid id PK
        string status
        string logs_ref
    }
    DATA_RESOURCES {
        uuid id PK
        string type
        string connection_ref "credentials live in vault"
    }

Full model (~16 tables) adds users/teams, shares, components (reuse registry), permissions, auditlogs and usagerecords — see [docs/data-model.md](docs/data-model.md).

Tech stack

| Concern | Choice | Why | |---|---|---| | Runtime substrate | Kubernetes (EKS Auto Mode on AWS; kind locally) | One substrate for all apps; namespace isolation; local→cloud is config, not rewrite | | Deploy mechanism | GitOps — Argo CD | Desired state in Git = versioned, audited, instant rollback | | Image builds | BuildKit + Cloud Native Buildpacks (Dockerfile supported) | Rootless, cached, auto-detects stacks | | Control plane | Spring Boot 3.3 / Java 21 + Flyway + PostgreSQL | Strong typing for the system of record | | AI services | Python (generator · Guardian · agents), MCP for tools | Polyglot by design; services talk HTTP | | Console | React + TypeScript | Built purely on the public control API | | Edge & identity | Identity-aware proxy + SSO (OIDC/SAML), ALB, wildcard DNS + auto-TLS | Every request authenticated before it reaches an app | | State & secrets | PostgreSQL (Aurora), Redis/Valkey queue, Secrets Manager + ESO | Metadata-only platform DB; credentials never in app code | | Observability | OpenTelemetry → Prometheus/Grafana; audit → SIEM | Event timeline as data — consumable by humans and agents |

What's in this repo (Milestone 0)

forge-ai-platform/
├─ services/control-plane/   # Spring Boot control-plane API — the brain
│  └─ src/main/java/io/forge/platform/
│     ├─ domain/             # App · Environment · Deployment · Build (+ enums)
│     ├─ repo/               # Spring Data repositories
│     ├─ service/            # AppService · DeploymentService (is_current logic)
│     └─ web/                # controllers · DTOs · global error handler (stable error codes)
├─ packages/db/migration/    # canonical Flyway SQL (apps · environments · deployments · builds)
├─ deploy/local/             # docker-compose: Postgres + Redis + local image registry
├─ samples/hello-python/     # FastAPI sample app — deployed by the pipeline in M1
├─ apps/cli/                 # `forge` CLI (M1)
├─ docs/                     # architecture deep-dive · ADRs · data model · roadmap
└─ Makefile                  # make infra · make api · make smoke

Run it locally

Prerequisites: Docker + Compose, JDK 21, Maven.

make infra    # start Postgres + Redis + local registry
make api      # run the control plane (Flyway creates the schema on boot)
make smoke    # create an app and list apps

# create an app (also creates its dev environment)
curl -s localhost:8080/apps -H 'content-type: application/json' \
  -d '{"slug":"hello","name":"Hello App","buildType":"CODE_DEPLOYED"}' | jq

# record a deployment
APP_ID=$(curl -s localhost:8080/apps | jq -r '.[0].id')
curl -s -X POST localhost:8080/apps/$APP_ID/deployments \
  -H 'content-type: application/json' -d '{"commitSha":"local-dev"}' | jq

# rollback = flip is_current to the previous deployment
curl -s -X POST localhost:8080/apps/$APP_ID/rollback | jq

| Method | Path | Purpose | |---|---|---| | POST | /apps | Create an app (+ its dev environment) | | GET | /apps · /apps/{id} | List / fetch apps | | POST | /apps/{id}/deployments | Record a deployment (wired to the real pipeline in M1) | | GET | /deployments/{id} | Deployment status + build records | | POST | /apps/{id}/rollback | Instant rollback (flip is_current) | | GET | /health | Liveness |

Roadmap

• [x] M0 — Local foundation: control-plane API + core schema + local infra (this repo)
• [ ] M1 — Walking skeleton: forge deploy ./hello-python → BuildKit build → local registry → Argo CD on kind → app live on a URL → forge rollback
• [ ] M2 — Cloud lift: Terraform to EKS Auto Mode, Aurora, ECR, ALB + ACM + Route 53, SSO — same code, config swap
• [ ] M3 — SDK & broker: keyless client SDK + governed connector broker (Path A data)
• [ ] M4 — AI layer: generator · Guardian · auto-fix, up the maturity ladder
• [ ] M5 — Governance at scale: catalog, marketplace, usage/cost showback

Design docs

| Doc | Contents | |---|---| | [docs/architecture.md](docs/architecture.md) | Full architecture deep-dive: 8-layer system view, build/deploy/run walkthroughs, gateway & broker, AI layer | | [docs/data-model.md](docs/data-model.md) | Complete metadata schema (~16 tables) with rationale | | [docs/adr/](docs/adr/) | Architecture Decision Records — K8s vs serverless, GitOps, BuildKit/Buildpacks, polyglot services, metadata-only DB, AI as layer 7 | | [docs/roadmap.md](docs/roadmap.md) | Milestone plan with definitions of done |

Author

Md Jasim Uddin — platform architecture & implementation. This repository is a public, sanitized reference of a platform design I authored; all company-specific details have been removed.

License

[MIT](LICENSE)

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jasimuddinrony
• Source: jasimuddinrony/forge-ai-platform
• License: MIT

Install and usage instructions live in the source repository linked above.