Home

SERP Framework

Service · Event · Runtime · Platform

SERP is a spec-bounded AI development platform for distributed C++ systems.

Large C++ systems are hard for AI to modify safely when architecture lives only in code, conventions, and developer memory. An unbounded coding session can touch the wrong layer, rewrite glue, break IPC, or silently drift away from the intended service contract.

SERP changes the shape of the problem. Architecture is written once in SerpIDL, then the framework derives the rest: C++ interfaces, transport adapters, process entry points, CMake wiring, deployment configurations, runtime inspection, and AI session scopes. AI works inside explicit contracts and enforced file boundaries. The unsafe infrastructure is generated or provided by the framework; the variable business logic remains editable.

The historical SERP pillars map directly to this model:

Pillar	Core idea
Service	System behavior is decomposed into isolated implementation scopes that AI agents can work on independently.
Event	Methods, properties, notifications, streams, timers, and watchdogs are typed and observable instead of hidden in ad hoc code.
Runtime	Running services can be inspected and driven directly, so AI debugging is based on live evidence rather than guesses.
Platform	Code generation, deployment specs, transports, lifecycle, logging, validation, and IDE tooling form the control plane around AI work.

---

How It Works

┌─────────────────────────────────────────────────────────────────┐
│                 SERP AI-Driven Development Loop                 │
└─────────────────────────────────────────────────────────────────┘

  requirements
         │
         ▼
  specs/serp.sidl          (formal architecture contract)
         │
         ▼
     serpgen validate       (contract validation)
         │
         ▼
     serpgen generate       (deterministic infrastructure)
         │
         ├──► gen/interfaces/     IFoo.h, IBar.h …
         │                        (pure virtual interface classes)
         │
         ├──► gen/base/           FooBase.h, BarBase.h …
         │                        (generated wiring, serialization, dispatch)
         │
         ├──► gen/services/       Foo.h/.cpp, Bar.h/.cpp …
         │                        (default stub implementations, generated once)
         │
         ├──► gen/mains/          main_monolith.cpp, main_foo.cpp …
         │                        (process entry points per deployment target)
         │
         └──► gen/adapters/       transport glue (inprocess / DBus / gRPC)
                  │
                  ▼
        scoped AI sessions
        (architecture, service, HMI, debug/fix)
                  │
                  ▼
         CMake build + tests
                  │
                  ▼
         runtime inspection
         (call methods, read state, observe events)
                  │
                  ▼
         compiled system
         (monolith binary or distributed set of per-service binaries)

---

Key Value Propositions

Property	What it means
Spec-bounded AI development	Architecture sessions design the system in specs/. Service sessions implement business logic in isolated src/ subtrees. Scope and context guards enforce these boundaries on every prompt and every file write.
Executable architecture contracts	Contracts are defined once in SerpIDL. C++ types, method signatures, dispatch tables, dependency wiring, and transport adapters are generated from the same source of truth.
Generated infrastructure	Files in gen/ are disposable and regenerated freely. AI does not hand-write IPC glue, process entry points, CMake wiring, or lifecycle configuration.
Transport-agnostic services	The same service code runs in-process, over DBus, over POSIX sockets, or over gRPC. Deployment topology is a spec decision, not an implementation rewrite.
Runtime-observable debugging	The Runtime Inspector and AI debug tools can call service methods, read properties, and observe notifications in a running deployment.
Parallel implementation by design	Service boundaries, generated contracts, and hard write scopes let multiple AI sessions implement different parts of the system without colliding.

---

Why This Is Different From Ordinary AI Coding

Ordinary AI coding	SERP AI-driven development
AI reads a large codebase and infers architecture from scattered implementation details.	AI starts from SerpIDL contracts that explicitly describe services, dependencies, data types, and deployments.
AI may edit build glue, IPC code, lifecycle code, or unrelated services.	AI works inside role-scoped write boundaries; generated infrastructure remains outside service implementation scope.
Parallel agents can overwrite each other or make incompatible assumptions.	Services are isolated by interface contracts, generated base classes, and per-session scopes.
Debugging often depends on human relay: "run this, paste logs, try again."	AI can inspect a running system through runtime tools: list methods, call methods, read state, and observe events.
Completion is conversational.	Completion is gated by validation, build, tests, scope checks, and runtime observation.

---

Documentation

Section	Contents
Quick Start	From zero to running generated service in ~15 minutes
Installation	Homebrew (macOS) and .deb (Ubuntu/Debian) install instructions
AI-Driven Development	The SERP development model: scoped agents, generated infrastructure, runtime investigation
Spec-First Workflow	Human and AI workflow around specs, validation, regeneration, build, and run
Architecture Language	SerpIDL reference: interfaces, types, service and deployment specs
Code Generator	serpgen commands, workspace layout, regeneration workflow
Framework Internals	Core concepts, services, methods, properties, transports, testing
VS Code Plugin	Extension features, commands, settings
Examples	Annotated walkthroughs of demo projects

---

Example Projects

• serp-demo — standalone example project demonstrating a multi-service workspace with generated code, CMake integration, and the full generate → build → run cycle.
• serp-mini-ivi — an AI-built IVI demonstration project showing SERP service decomposition, generated infrastructure, multiprocess deployment, and runtime debugging. It is a platform showcase, not a production-ready IVI stack.
• serp-vhal — a SERP-generated VHAL for Android Automotive OS. Bridges SERP vehicle services to the AAOS AIDL VHAL interface so that CarService and AAOS apps receive live vehicle property events from SERP services running on the device.

---

License

SERP is licensed under the Polyform Noncommercial 1.0.0 license. It is free to use for noncommercial purposes. See LICENSE for the full terms.