AFrame

Auto-Generated, Data-Driven Frontend Framework

AFrame is a complete full-stack framework that generates production-ready React/MUI components and C# backend controllers directly from OpenAPI specifications. Build complete CRUD applications in minutes without writing UI code.

🎯 What is AFrame?

AFrame bridges the gap between your API specification and your application by:

Parsing your OpenAPI 3.x spec
Inferring component types and behaviors
Generating React components, hooks, and configuration
Enforcing backend API structure with C# controller interfaces

The result: A fully functional, themed, validated UI that stays in sync with your API.

✨ Features

🚀 Zero-Config Generation - Point at OpenAPI spec, get complete UI
🎨 Zero CSS Required - Everything via MUI theme tokens
📊 Full CRUD Components - Cards, DataGrids, Forms, Search, Infinite Scroll
🔗 Smart Relations - Auto-detected from $ref, with modals and grids
⚙️ Highly Configurable - Override at global, entity, or component level
🪝 React Query Hooks - Built-in caching and state management
🛡️ Type Safe - Full TypeScript support throughout
🔌 Backend Enforcement - C# controller interfaces ensure API consistency
📚 Complete Documentation - Astro-based docs site with examples

📦 What's Included

Frontend Framework (`/src`)

OpenAPI parser
Code generator
Runtime components (Card, DataGrid, Search, etc.)
React Query hooks
Theming system
Configuration system

Backend Library (`/backend`)

Controller interface (IAFrameController)
Base controller implementation
Entity interface (IEntity)
Service interface (IEntityService)
Standard response formats
Example User and Role controllers

Demo Application (`/demo`)

Complete working example
User and Role management
Mock API with sample data
Multiple view types (Grid, Cards, Search)
Full CRUD operations

Documentation Site (`/docs`)

Getting started guide
Architecture overview
API inference rules
Configuration guide
Code examples
Deployment instructions

🚀 Quick Start

1. Install Dependencies

npm install

2. Run the Demo

npm run dev

Visit http://localhost:5173 to see the demo with User and Role management.

3. Generate Components from Your API

npm run generate -- -i your-api.yaml -o ./generated/aframe

4. Use in Your App

import { AFrameProvider } from 'aframe';
import { A } from './generated/aframe';

const config = {
  api: { baseUrl: 'https://api.example.com' },
  theme: { palette: { primary: { main: '#6366f1' } } },
};

function App() {
  return (
    <AFrameProvider config={config}>
      <A.User.DataGrid />
      <A.User.CreationCard />
    </AFrameProvider>
  );
}

📁 Project Structure

aframe/
├── src/                          # Frontend framework
│   ├── cli/                      # Code generator CLI
│   ├── parser/                   # OpenAPI parser
│   ├── generator/                # Code generator
│   ├── runtime/
│   │   ├── components/           # React components
│   │   ├── hooks/                # React Query hooks
│   │   └── context/              # Theme & config
│   ├── types/                    # TypeScript types
│   └── index.ts                  # Main exports
│
├── backend/                      # C# backend library
│   ├── Core/
│   │   ├── IEntity.cs            # Base entity interface
│   │   ├── IEntityService.cs     # Service contract
│   │   └── ListResponse.cs       # Standard response
│   ├── Controllers/
│   │   ├── IAFrameController.cs  # Controller interface
│   │   └── AFrameControllerBase.cs # Base implementation
│   ├── Models/
│   │   ├── User.cs               # User entity & DTOs
│   │   └── Role.cs               # Role entity & DTOs
│   ├── Examples/
│   │   ├── UserController.cs     # Example controller
│   │   └── RoleController.cs     # Example controller
│   └── AFrame.Backend.csproj
│
├── demo/                         # React demo app
│   ├── src/
│   │   ├── generated/            # Generated components
│   │   ├── App.tsx               # Demo application
│   │   ├── main.tsx              # Entry point
│   │   └── mockApi.ts            # Mock API
│   ├── index.html
│   ├── tsconfig.json
│   └── README.md
│
├── docs/                         # Documentation site (Astro)
│   ├── src/
│   │   ├── layouts/Layout.astro  # Main layout
│   │   └── pages/
│   │       ├── index.astro       # Homepage
│   │       ├── examples.astro    # Code examples
│   │       └── docs/
│   │           ├── getting-started.astro
│   │           ├── how-it-works.astro
│   │           ├── frontend.astro
│   │           ├── backend.astro
│   │           ├── api-inference.astro
│   │           └── configuration.astro
│   ├── astro.config.mjs
│   └── package.json
│
├── package.json                  # Root dependencies
├── tsconfig.json                 # TypeScript config
├── vite.config.ts                # Vite config
├── .gitignore
└── README.md                     # This file

🔄 How It Works

The Three Layers

OpenAPI Spec
    ↓
[Parser] → Extracts entities, fields, relations, operations
    ↓
[Generator] → Emits React components and hooks
    ↓
React Components + Configuration

Inference Rules

AFrame intelligently infers how to render your data:

OpenAPI	Component	Example
`string`	TextField	firstName
`string, format: email`	EmailField	user@example.com
`string, format: date`	DateField	2024-01-25
`integer`	NumberField	42
`boolean`	Switch	true/false
`string, enum`	Select	active, pending
`array of $ref`	RelationGrid	List of roles

Operations

GET /resource → DataGrid, InfiniteScroll, Search
GET /resource/{id} → Card (view mode)
POST /resource → CreationCard
PATCH /resource/{id} → Card (edit mode)
DELETE /resource/{id} → Delete button

💻 Frontend Framework

Generated Components

Each entity gets these components:

<A.User.Card id="123" />              // View/edit single
<A.User.CreationCard />               // Create new
<A.User.DataGrid />                   // Paginated table
<A.User.Search />                     // Search & filter
<A.User.ListItem data={user} />       // List item
<A.User.InfiniteScroll />             // Infinite scroll
<A.User.Fields.Email />               // Individual field
<A.User.Relations.Roles.DataGrid />   // Relation grid

React Hooks

const { data, isLoading } = useEntity('User', '123');
const { data, isLoading } = useEntityList('User', { page: 1 });
const mutation = useCreateEntity('User');
const mutation = useUpdateEntity('User');
const mutation = useDeleteEntity('User');

Configuration

const config = {
  api: {
    baseUrl: 'https://api.example.com',
    headers: { 'Authorization': 'Bearer token' },
  },
  theme: {
    palette: {
      primary: { main: '#6366f1' },
      secondary: { main: '#ec4899' },
    },
  },
  Card: {
    // optional component-level settings
  },
  // optional entity specific settings
  entities: {
    User: {
      // optional settings to override globals
      props: {
        title: (e) => `${e.firstName} ${e.lastName}`,
        subtitle: 'email',
      },
      styles: {
        Card: { elevation: 2 },
        TextField: { size: 'small' },
      },
      theme: {
        palette: { primary: { main: '#4A6CF7' } },
      },
      fields: {
        email: {
          validation: (v) => v?.includes('@') ? undefined : 'Invalid',
        },
      },
    },
  },
};

🛡️ Backend Library (C#)

Core Interfaces

// All entities must implement IEntity
public interface IEntity
{
    string Id { get; set; }
    DateTime CreatedAt { get; set; }
    DateTime UpdatedAt { get; set; }
}

// All services must implement IEntityService
public interface IEntityService<TEntity, TCreateDto, TUpdateDto>
{
    Task<ListResponse<TEntity>> GetAllAsync(int page, int pageSize, string? search);
    Task<TEntity?> GetByIdAsync(string id);
    Task<TEntity> CreateAsync(TCreateDto dto);
    Task<TEntity> UpdateAsync(string id, TUpdateDto dto);
    Task DeleteAsync(string id);
    Task<bool> ExistsAsync(string id);
}

// All controllers must implement IAFrameController
public interface IAFrameController<TEntity, TCreateDto, TUpdateDto>
{
    Task<ActionResult> GetAll(int page, int pageSize, string? search);
    Task<ActionResult> GetById(string id);
    Task<ActionResult> Create(TCreateDto dto);
    Task<ActionResult> Update(string id, TUpdateDto dto);
    Task<ActionResult> Delete(string id);
}

Creating a Controller

[ApiController]
[Route("api/[controller]")]
public class UserController : AFrameControllerBase<User, CreateUserDto, UpdateUserDto>
{
    public UserController(IEntityService<User, CreateUserDto, UpdateUserDto> service)
        : base(service) { }
    
    // All CRUD endpoints automatically provided
}

API Endpoints

GET    /api/users                    # List with pagination
GET    /api/users/{id}               # Get single
POST   /api/users                    # Create
PATCH  /api/users/{id}               # Update
DELETE /api/users/{id}               # Delete

📚 Documentation

Full documentation available in /docs:

cd docs
npm install
npm run dev

Visit http://localhost:3000 for:

Getting started guide
Architecture overview
API inference rules
Configuration options
Code examples
Deployment guides

🎨 Demo Application

The demo showcases a complete user management application:

npm run dev

Features:

User and Role management
Multiple view types (Grid, Cards, Search)
Full CRUD operations
Relation handling (Users ↔ Roles)
Mock API with sample data
Responsive Material Design UI

🔧 Commands

# Install dependencies
npm install

# Run demo app
npm run dev

# Generate components from OpenAPI
npm run generate -- -i api.yaml -o ./generated

# Build frontend
npm run build

# Build documentation
cd docs && npm run build

# Deploy documentation
cd docs && npm run build && netlify deploy --prod --dir=dist

🚀 Deployment

Frontend

Vite-based React app
Deploy to Netlify, Vercel, AWS S3, etc.

Backend

ASP.NET Core 8.0+
Deploy to Azure, AWS, Docker, etc.

Documentation

Static Astro site
Deploy to Netlify, Vercel, GitHub Pages, etc.

See /docs/DEPLOYMENT.md for detailed instructions.

📖 Example Usage

Complete User Management App

import React, { useState } from 'react';
import { AFrameProvider } from 'aframe';
import { A } from './generated/aframe';

function App() {
  const [selectedId, setSelectedId] = useState(null);

  return (
    <AFrameProvider config={config}>
      <A.User.Search />
      <A.User.DataGrid onRowClick={(row) => setSelectedId(row.id)} />
      {selectedId && <A.User.Card id={selectedId} />}
    </AFrameProvider>
  );
}

Backend Controller

[ApiController]
[Route("api/[controller]")]
public class UserController : AFrameControllerBase<User, CreateUserDto, UpdateUserDto>
{
    public UserController(IEntityService<User, CreateUserDto, UpdateUserDto> service)
        : base(service) { }
}

🤝 Contributing

Contributions welcome! Please:

Fork the repository
Create a feature branch
Make your changes
Submit a pull request

📝 License

MIT

🔗 Links

❓ FAQ

Q: Do I need to write CSS? A: No! Everything is controlled through MUI theme tokens.

Q: Can I customize components? A: Yes! Override at global, entity, or component level.

Q: Does it support TypeScript? A: Yes! Full TypeScript support throughout.

Q: Can I use it with my existing API? A: Yes! Just create an OpenAPI spec for your API.

Q: What about relations between entities? A: Automatically detected from $ref in your OpenAPI spec.

Name		Name	Last commit message	Last commit date
Latest commit History 14 Commits
backend		backend
demo		demo
docs		docs
scripts		scripts
src		src
.gitignore		.gitignore
DOCUMENTATION.md		DOCUMENTATION.md
LICENSE		LICENSE
PUBLISHING.md		PUBLISHING.md
README.md		README.md
aframe.sln		aframe.sln
package-lock.json		package-lock.json
package.json		package.json
specification.md		specification.md
test_open_api.yaml		test_open_api.yaml
tsconfig.build.json		tsconfig.build.json
tsconfig.json		tsconfig.json
vite.config.ts		vite.config.ts

Folders and files

Latest commit

History

Repository files navigation