System Architecture
Fascia separates design-time intelligence from runtime execution through a two-plane architecture. The Control Plane handles spec design, validation, and deployment. The Data Plane runs deterministic execution logic inside the customer's own cloud infrastructure.
Architecture Diagram
User ─── Chat Studio ──┐
Flow Studio ───┤── Build Phase (Fascia-hosted)
Deploy ────────┘ ├── Spec Registry
├── Safety Agent
└── Risk Engine
Runtime (Customer GCP)
├── Cloud Run (Executor)
├── Cloud SQL (Postgres)
├── Cloud Scheduler
├── Secret Manager
└── Pub/Sub (optional)
Two-Plane Architecture
Control Plane (Fascia-hosted)
The Control Plane is where design happens. It is hosted and managed by Fascia.
| Component | Purpose |
|---|---|
| Chat Studio | Conversational interface for designing entities, tools, and flows using natural language. LLM-powered -- translates user intent into structured specs. |
| Flow Studio | Visual graph editor (built with ReactFlow) for designing Tool execution logic. Supports drag-and-drop node placement, connection validation, and real-time type checking. |
| Spec Registry | Versioned storage for all Entity, Tool, Policy, and Invariant specifications. Specs are immutable once versioned -- changes create new versions. |
| Safety Agent | AI-powered analysis component that reviews Tool specs, detects unsafe patterns, suggests fixes, and generates test cases. Uses multi-model cross-checking across different LLM families for reliability. Operates only during the build phase. |
| Risk Engine | Evaluates Tool flow graphs against risk classification rules. Assigns Green, Yellow, or Red risk levels. Red tools are blocked from deployment. |
The Control Plane stores only specs, metadata, and deployment records. It never stores or processes customer business data.
Data Plane (Customer GCP)
The Data Plane is where execution happens. All components run inside the customer's own GCP project under the BYOC model.
| Component | Purpose |
|---|---|
| Cloud Run (Executor) | Runs the compiled Tool execution logic. The Executor is a Go binary that interprets SpecBundles (compiled specs) and executes flow graphs deterministically. |
| Cloud SQL (Postgres) | One PostgreSQL instance per workspace. Stores all business data for the customer's application. Auto-provisioned during deployment. |
| Cloud Scheduler | Invokes cron-triggered Tools on schedule. Managed via Terraform during deployment. |
| Secret Manager | Stores all sensitive data: API keys, OAuth client secrets, database passwords, JWT signing keys. Secrets never leave the customer's GCP project. |
| Pub/Sub | (Optional) Enables queue-triggered Tools and event-driven workflows between Tools. |
Tech Stack
| Layer | Technology | Purpose |
|---|---|---|
| Frontend | React + TypeScript + ReactFlow | Chat Studio, Flow Studio, Management Console |
| Platform Backend | Node.js + TypeScript + Fastify | Spec Registry, Safety Agent, Risk Engine, Deploy Pipeline |
| Executor | Go | Flow graph execution on Cloud Run |
| Platform Database | PostgreSQL | Spec Registry, workspace metadata, deployment records |
| Customer Database | PostgreSQL (Cloud SQL) | One instance per workspace, auto-provisioned |
| LLM | Multi-model cross-check | Claude + GPT-4 (different families), Gemini fallback |
Key Technology Decisions
Why Go for the Executor?
The Executor runs on Cloud Run in the customer's GCP project. Every API call made by end users of the customer's product hits the Executor, making cold start time critical. Go achieves approximately 50ms cold start on Cloud Run, compared to 300-500ms for Node.js. The Executor is a well-bounded component -- once the flow graph engine and node handlers are implemented, changes are infrequent. The performance advantage justifies maintaining a dual-language codebase.
Why Fastify for the Platform Backend?
Fascia's core abstraction is the spec, and specs are defined as JSON Schemas. Fastify provides native JSON Schema validation via Ajv, meaning route-level schema declarations flow naturally from domain definitions to API validation to auto-generated Swagger documentation. This alignment eliminates a translation layer that would be required with Zod-based frameworks (Hono) or decorator-based frameworks (NestJS).
Why PostgreSQL?
PostgreSQL serves dual roles. JSONB columns store spec content efficiently while maintaining the flexibility to evolve spec schemas. Relational tables handle workspace metadata, deployment records, and audit logs with full transactional integrity. The same technology is used for both the platform database and customer databases, simplifying operations and reducing the surface area for bugs.
Core Design Principles
| Principle | Description |
|---|---|
| Spec is Source of Truth | All runtime behavior is derived from structured specs. Entities, Tools, and Policies are defined declaratively and compiled into execution artifacts. |
| No LLM at Runtime | LLM (Claude, GPT, Gemini) is used only during the build/design phase in the Control Plane. The Executor never calls any LLM API. All runtime behavior is deterministic. |
| Deterministic Execution | Every Tool execution follows the same 9-step contract. Given the same input and database state, the output is always the same. |
| Policy-First | Unsafe operations are detected and blocked at design time, before they can ever run. The Risk Engine prevents deployment of tools with structural safety issues. |
| BYOC | All customer data and runtime infrastructure lives in the customer's own GCP project. Fascia never stores customer business data. See BYOC Deployment. |
Execution Contract
Every Tool execution follows this exact 9-step sequence. No LLM is involved. No exceptions.
| Step | Operation | Description |
|---|---|---|
| 1 | Validate input | Check the request payload against the Tool's declared input JSON Schema. |
| 2 | Authorize | Verify the JWT token, check RBAC roles, and apply row-level access policies. |
| 3 | Policy check | Evaluate all referenced Policies (rate limits, budget checks, row limits). |
| 4 | Start transaction | Begin a database transaction for all subsequent write operations. |
| 5 | Execute flow graph | Traverse the DAG node by node, following edges. Each node performs its operation (read, write, transform, etc.). |
| 6 | Enforce invariants | Check all invariants on modified entities. If any invariant fails, the transaction is rolled back. |
| 7 | Commit / rollback | Commit the transaction if all steps succeeded. Rollback on any failure. |
| 8 | Write audit log | Record the operation in the audit log (timestamp, user, tool, operation, before/after state). |
| 9 | Return output | Send the normalized response to the caller, matching the Tool's output JSON Schema. |
Data Flow
The lifecycle of a spec from design to execution:
- Design -- The user creates or modifies a spec through Chat Studio or Flow Studio in the Control Plane.
- Validate -- The Safety Agent analyzes the spec for unsafe patterns. The Risk Engine assigns a risk level.
- Store -- The validated spec is stored as a new immutable version in the Spec Registry.
- Compile -- The spec is compiled into a SpecBundle (a self-contained execution artifact).
- Deploy -- Terraform provisions or updates the customer's GCP infrastructure. The SpecBundle is deployed to Cloud Run.
- Execute -- End users invoke Tools via HTTP. The Executor loads the SpecBundle and follows the Execution Contract.
See Also
- BYOC Deployment -- How runtime infrastructure is provisioned in the customer's GCP project
- Entity Spec Schema -- The fundamental business object abstraction
- Tool Spec Schema -- Executable server logic definitions
- Risk Classification Rules -- How the Risk Engine evaluates Tool safety