System Architecture

Deep dive into the technical architecture and component breakdown

Component Breakdown

Understanding how each piece of the ecosystem works internally

Schema Processor

S2ai.builder converts schema.mmd to a full stack app

  • Parses Mermaid ER diagram syntax
  • Extracts entities, fields, and relationships
  • Processes validation rules and UI hints
  • Generates S2ai server

Code Generator

s2ai.builder generates complete server implementation

  • FastAPI application structure
  • CRUD routers for each entity
  • Database adapters
  • Validation middleware
  • OpenAPI documentation

Runtime Server

s2ai.server is the generated FastAPI application

  • REST API endpoints
  • Database operations
  • Data validation
  • Metadata endpoints
  • System/Database Admin functions
  • Authentication & authorization

REST API is the default router which is swappable and isolated, allowing other frameworks to be used such as GraphQL.

Database Drivers

Part of generated server with multi-database support

  • MongoDB adapter
  • PostgreSQL adapter
  • SQLite adapter
  • Elasticsearch adapter

Metadata Consumption

How s2ai.face (UI) and s2ai.genius (AI assistant) use metadata

  • Fetch metadata at runtime from server
  • Parse entity definitions
  • Generate UI components dynamically
  • Apply validation rules
  • Enforce RBAC permissions

Schema Definition Example

schema.mmd defines entities, validation rules, UI hints, and service configurations

schema.mmdmermaid
%% @dictionary main { email: "^[a-zA-Z0-9](...)*@[a-zA-Z0-9-]+...", url: "^https?://..." }

erDiagram
    User {
        String username %% @validate { required: true, min_length: 3 }, @unique
        String email    %% @validate { required: true, pattern: { regex: "dictionary=main.email" } }, @unique
        String password %% @validate { required: true, min_length: 8 } @ui { display: "secret" }
        Boolean isActive %% @validate { default: true }
        ObjectId roleId
        
        %% @ui { title: "Users", icon: "fa-user", iconColor: "#3498db" }
        %% @service { authn: { provider: "cookies.redis", route: 'login/user' } }
    }
    
    Role {
        String role        %% @validate { required: true } @unique
        Json permissions   %% @validate { required: true }
        
        %% @service { authz: { provider: "rbac" } }
        %% @ui { title: "Roles & Permissions", icon: "fa-users" }
    }
    
    Role ||--o{ User: ""

Validation Rules

@validate annotations define field requirements, formats, and constraints

UI Hints

@ui annotations control how fields appear in s2ai.face

Service Config

@service annotations define authentication and authorization

Relationships

ER diagram syntax defines entity relationships

Data Flow

Understanding how data moves through the system

Build Time

schema.mmd
→
s2ai.builder
→
s2ai.server + OpenAPI Docs + ER Diagram

Full-time schema validation at runtime in both the server and the UI

Runtime

s2ai.face

Browser GUI

s2ai.genius

AI Integration

Runtime components access metadata from the s2ai server(s) dynamically

Key Architecture Principles

Schema-First Design

Everything starts with schema.mmd - the single source of truth

Code Generation

s2ai.builder generates production-ready code, not templates

Metadata-Driven Architecture

Components automatically adapt through metadata for maximum flexibility

Runtime Data Validation

Validation happens at runtime in the server, ensuring data integrity

Multi-Database Abstraction

Database adapters provide a consistent interface across different databases