App Blueprint

The app blueprint ({app}.app.json) is the master document for your Radish application. It defines high-level metadata, audience, workflows, features, and entity overview. Other blueprints (types, roles) derive their content from it.

Structure

{
  "version": 1,
  "app": { },
  "audience": { },
  "workflows": [ ],
  "categories": [ ],
  "style": { },
  "features": { },
  "entityOverview": { },
  "accessPatterns": { },
  "database": { }
}

Only version and app (with name and description) are required. All other sections are optional.

Sections

app (required)

Core application identity.

{
  "app": {
    "name": "Library",
    "displayName": "Library Management System",
    "description": "A comprehensive library system for managing books, authors, members, and loans with full catalog search and lending workflows",
    "version": "0.1.0",
    "domain": "education",
    "tags": ["library", "books", "lending", "catalog"]
  }
}

Field	Required	Description
name	Yes	Application identifier (PascalCase or camelCase, 1-100 chars)
displayName	No	Human-readable name for UI
description	Yes	Rich description of purpose and functionality (1-2000 chars). Write detailed descriptions — this drives downstream generation.
version	No	Semantic version (x.y.z)
domain	No	Business domain (e.g., education, e-commerce, healthcare)
tags	No	Searchable categorization tags

audience

Define user personas to guide permission design and UI decisions.

{
  "audience": {
    "primary": "Library patrons searching and borrowing books",
    "secondary": "Librarians managing catalog, processing loans, and helping patrons",
    "admin": "System administrators managing users, roles, and system settings"
  }
}

workflows

Key user journeys that define how people interact with the application.

{
  "workflows": [
    {
      "name": "Borrow Book",
      "actor": "patron",
      "description": "Patron searches catalog, selects available book, requests loan. Librarian reviews and approves. System records due date and updates availability."
    },
    {
      "name": "Return Book",
      "actor": "librarian",
      "description": "Librarian scans returned book, system closes loan, updates availability, calculates any late fees."
    }
  ]
}

Each workflow requires name and description. The actor field identifies which user persona performs the workflow.

categories

Optional content categorization for organizing entities or content.

{
  "categories": [
    {
      "name": "Fiction",
      "subcategories": ["Literary", "Science Fiction", "Mystery", "Romance"]
    },
    {
      "name": "Non-Fiction",
      "subcategories": ["History", "Science", "Biography"]
    }
  ]
}

style

Branding hints for UI generation.

{
  "style": {
    "theme": "radish-admin",
    "tone": "professional",
    "palette": "warm earth tones",
    "typography": "clean sans-serif",
    "layout": "sidebar navigation with content area",
    "icons": "outline style",
    "imagery": "minimal, functional"
  }
}

All fields are optional free-text strings that guide UI layer generation.

features

Boolean flags indicating which platform features to enable.

{
  "features": {
    "auth": true,
    "roles": true,
    "adminPanel": true,
    "api": true,
    "search": true,
    "pagination": true,
    "fileUploads": false,
    "notifications": false,
    "analytics": false,
    "scheduling": false,
    "logging": true
  }
}

Feature	Description
auth	Authentication system (login, registration, JWT)
roles	Role-based access control
adminPanel	Administrative panel
api	REST API endpoints
search	Full-text search functionality
pagination	Paginated list responses
fileUploads	File upload capability
notifications	Notification system
analytics	Analytics and reporting
scheduling	Calendar/scheduling features
logging	Application logging

entityOverview

High-level entity groupings by domain concern. This is not where you define fields — that's the types blueprint. This section provides a conceptual map of your data model.

{
  "entityOverview": {
    "catalog": [
      { "Book": "Books in the library catalog. Owned by system." },
      { "Author": "Book authors with biographical information." },
      { "Category": "Book categories and genres." }
    ],
    "lending": [
      { "Loan": "Active book loans tracked by member and due date." },
      { "Reservation": "Book hold requests from members." }
    ],
    "membership": [
      { "Member": "Library members with borrowing privileges." }
    ]
  }
}

Entity names should be PascalCase. Don't include built-in entities (User, Profile, Role, Permission, ApiKey, Setting) — these are generated automatically.

accessPatterns

Define who can do what at each access level.

{
  "accessPatterns": {
    "public": ["Browse catalog", "Search books", "View author profiles"],
    "authenticated": ["Borrow books", "View own loans", "Place reservations"],
    "librarian": ["Manage catalog", "Process loans", "Manage members"],
    "admin": ["Manage users", "Configure system", "View reports"]
  }
}

database

Database engine configuration.

{
  "database": {
    "type": "mongodb",
    "name": "library"
  }
}

Supported types: mongodb, postgresql, mysql.

Complete Example

{
  "version": 1,
  "app": {
    "name": "Library",
    "displayName": "Library Management System",
    "description": "A comprehensive library management system for tracking books, authors, members, and lending operations. Supports catalog browsing, book borrowing, and administrative functions.",
    "version": "0.1.0",
    "domain": "education",
    "tags": ["library", "books", "lending"]
  },
  "audience": {
    "primary": "Library patrons searching and borrowing books",
    "secondary": "Librarians managing catalog and processing loans",
    "admin": "System administrators managing users and settings"
  },
  "workflows": [
    {
      "name": "Browse and Borrow",
      "actor": "patron",
      "description": "Patron searches catalog by title or author, views book details, requests loan if available"
    },
    {
      "name": "Process Returns",
      "actor": "librarian",
      "description": "Librarian receives returned book, marks loan complete, updates availability"
    }
  ],
  "features": {
    "auth": true,
    "roles": true,
    "adminPanel": true,
    "api": true,
    "search": true,
    "pagination": true,
    "fileUploads": false,
    "notifications": true,
    "analytics": false,
    "scheduling": false,
    "logging": true
  },
  "entityOverview": {
    "catalog": [
      { "Book": "Books in the library catalog. Owned by system." },
      { "Author": "Book authors with biographical info." }
    ],
    "lending": [
      { "Loan": "Active book loans tracked by member and due date." }
    ]
  },
  "accessPatterns": {
    "public": ["Browse catalog", "Search books"],
    "authenticated": ["Borrow books", "View own loans"],
    "admin": ["Manage catalog", "Manage members", "Override loans"]
  },
  "database": {
    "type": "mongodb",
    "name": "library"
  }
}

Best Practices

Write Rich Descriptions

The app.description field drives downstream generation. Be specific about what the application does, who uses it, and why.

{
  "description": "A comprehensive library management system for tracking books, authors, members, and lending operations. Supports catalog browsing with full-text search, book borrowing with due date tracking, and administrative functions including member management and overdue notifications."
}

Define Specific Workflows

Workflows should describe real user journeys, not abstract operations.

{
  "workflows": [
    {
      "name": "Borrow Book",
      "actor": "patron",
      "description": "Patron searches catalog, selects available book, requests loan. Librarian reviews and approves. System records due date and updates availability."
    }
  ]
}

Group Entities by Domain

Use meaningful domain group names in entityOverview to organize your data model conceptually.

Don't Duplicate Other Blueprints

The app blueprint is for high-level intent. Don't define:

• Individual entity fields (that's types.json)
• Routes or API endpoints (generated automatically)
• Specific permissions (that's roles.json)
• Implementation details

Next Steps

• Entity Definitions — Define entity fields in types.json
• Roles & Permissions — Define roles in roles.json
• Blueprint Examples — Real-world blueprint patterns