1. What Is a Mindbricks Project?

A Mindbricks Project is the root ontology of your application—the highest-level definition from which every microservice, every data model, every authentication rule, every BFF view, and every API workflow is generated. It is the source of truth for your entire backend architecture.

Think of it as the DNA of your software system.

• A frontend developer sees MindbricksProject as a stable contract of services and data shapes.

• A backend developer sees it as a structured, declarative specification of microservices.

• A product owner sees a clear mapping from business requirements to actual software behavior.

• An AI agent sees it as a full semantic model that guides deterministic code generation.

A Mindbricks Project is always represented as a JSON object conforming to the ontology described in the patterns document . Architects may create this JSON manually or through the visual Mindbricks Studio UI. AI agents (MindAI) use the same ontology to design, refine, and extend your project.

High-Level Structure of a Mindbricks Project

A new project generally includes:

• Project Settings (metadata, integrations, environment, Stripe, AI, pipelines)

• Authentication module

• BFF Service (optional but highly recommended)

• Notification Service (optional)

• Library module (shared utilities)

• Microservices (each with data objects, business APIs, library, edge controllers)

From a philosophical lens, the Mindbricks Project is the world in which your application will unfold: it defines the actors, their abilities, their relationships, the laws of your domain, and the flows that govern behavior. Code generation then becomes a process of bringing this world into existence.

MindbricksProject JSON Schema (Top Level)

The top-level structure is defined as:

{
  "projectSettings": { ... },
  "authentication": { ... },
  "bffService": { ... },
  "notificationService": { ... },
  "library": { ... },
  "services": [ ... ]
}

Each field corresponds to a conceptual module explained in this document and the full ontology.

2. Project Settings

Project Settings are the foundation of every Mindbricks Project. They define identity, environment, infrastructure, and high-level integrations.

Think of them as the compass that tells all generated microservices how to behave.

Ontology Reference: ProjectSettings

2.1 Purpose of Project Settings

Project Settings answer fundamental questions:

• What is the project called?

• What global environment variables exist?

• Does the project use Stripe? AI models? CORS control?

• Should Mindbricks generate CI/CD pipeline files?

• What external providers (AWS S3, Google Maps, Telegram, etc.) will be used?

Every service generated inside the project inherits these settings. They represent a meta-configuration layer governing the entire ecosystem.

3.****projectSettings.basicSettings

JSON Structure

"projectSettings": {
  "basicSettings": {
    "name": "Babil",
    "fullname": "Babil Online Book Store",
    "description": "Babil Online Book Store is a project to sell books online.",
    "avatar": "https://example.com/logo.png",
    "frontendDocument": "# UX Guidelines
The application behaves as...",
    "hasAuthentication": true,
    "ignoreDeploymentSpecificFiles": false,
    "customVariables": [
      { "name": "PUBLIC_URL", "value": "https://babil.mindbricks.co" }
    ]
  }
}

UI Navigation

Project → Project Settings → Basic Settings

Conceptual Explanation

• name: Short internal codename. Used in folder names, bucket IDs, URLs.

• fullname: Human-readable product name.

• description: Long textual description used in documentation.

• avatar: A logo for dashboards and docs.

• frontendDocument: A unique Mindbricks concept—this is a UX behavior document intended for frontend developers or AI-driven frontend generators. It describes "How the app behaves" rather than backend internals.

• hasAuthentication: Enables the built-in Auth module. Most projects keep this true.

• ignoreDeploymentSpecificFiles: Useful for teams managing their own CI/CD or infra.

• customVariables: Arbitrary environment variables shared across all services.

4. Stripe Settings

If the project uses Stripe for payments, configure credentials here.

Ontology Reference: StripeSettings, StripeSettingsConfig

JSON Example

"stripeSettings": {
  "useStripe": true,
  "configuration": {
    "testPublicKey": "pk_test_xxx",
    "testSecretKey": "sk_test_xxx",
    "livePublicKey": null,
    "liveSecretKey": null
  }
}

UI Navigation

Project → Project Settings → Stripe Settings

Explanation

Mindbricks does not provide a managed Stripe account. You bring your own keys, and Mindbricks generates all required order/payment flows.

5. AI Settings

Defines API keys for OpenAI or Anthropic to enable AI-based features inside Business APIs, workflows, and system-level decisions.

Ontology Reference: AiSettings

JSON Example

"aiSettings": {
  "openAiApiKey": "sk-xxxxxx",
  "anthropicApiKey": null
}

UI Navigation

Project → Project Settings → AI Settings

Use Case

• Product recommendations

• AI validation

• Transformations in workflows (AiCallAction, RefineByAiAction)

6. CORS Settings

Controls cross-origin access for all services.

Ontology Reference: CorsSettings & CorsSettingsConfig

"corsSettings": {
  "useCorsControl": true,
  "configuration": {
    "allowedOrigins": ["https://myapp.com"],
    "allowAllSubdomains": true
  }
}

Explanation

If your app is hosted under multiple subdomains (e.g., tenant1.myapp.com, tenant2.myapp.com), allowAllSubdomains = true avoids repetitive origin whitelisting.

7. Pipeline Templates

These are EJS templates that generate CI/CD files (like .gitlab-ci.yml) for every service.

Ontology Reference: PipelineTemplate

JSON Example

"pipelineTemplates": [
  {
    "filename": ".gitlab-ci.yml",
    "template": "<%= serviceName %>:
  script: echo Building..."
  }
]

UI Navigation

Project → Project Settings → Pipeline Templates

8. Integrations

Allows defining reusable client configs for third-party providers like:

• Amazon S3

• Google Gemini

• Google Maps

• Telegram (and more, according to integration registry)

Ontology Reference: IntegrationConfiguration & IntegrationProvider

JSON Example

"integrations": [
  {
    "provider": "amazonS3",
    "configuration": [
      { "name": "region", "value": "`eu-central-1`" },
      { "name": "accessKeyId", "value": "`process.env.AWS_KEY`" },
      { "name": "secretAccessKey", "value": "`process.env.AWS_SECRET`" }
    ]
  }
]

Use Case

These configurations are later used inside Business APIs via IntegrationAction.

9. Complete ProjectSettings JSON Template

{
  "projectSettings": {
    "basicSettings": { ... },
    "stripeSettings": { ... },
    "aiSettings": { ... },
    "corsSettings": { ... },
    "pipelineTemplates": [ ... ],
    "integrations": [ ... ]
  }
}

This template grows as the project evolves, but these are the essential chapters.

10. Understanding MindbricksProject as a Philosophical Model

To design a system in Mindbricks is to create a semantic world:

• Objects define the beings in this world.

• Properties define their essence.

• Services define the boundaries separating domains.

• Authentication defines identity and responsibility.

• Business APIs define possible actions and rules.

• Views define how knowledge aggregates and becomes accessible.

• Events define how the world reacts.

The project JSON is not merely a configuration; it is a structured theory of your application that Mindbricks interprets to generate a functioning microservice universe.

In this sense, writing a Mindbricks project is both an engineering act and a philosophical exercise— a bridge between abstract domain thinking and concrete, executable architecture.