Architecture Overview
How organizations, workspaces, and apps fit together in MechaMental.
MechaMental is organized in a three-level hierarchy that provides clean isolation, access control, and resource management at every level.
Platform Hierarchy
Organization
├── Workspace
│ ├── App
│ │ ├── Dashboard
│ │ ├── Namespaces
│ │ ├── Augmentations (Pipelines)
│ │ ├── Environments
│ │ ├── Tokens
│ │ ├── Releases
│ │ └── Settings
│ ├── Models (entitlements from org)
│ ├── Tools
│ └── Sources
└── Models (managed at org level)Organization
The top-level tenant in MechaMental. An organization manages:
- Members — users and their roles across the platform
- Model catalog — all available models from configured providers
- Provider accounts — credentials for LLM providers (Anthropic, OpenAI, Google, etc.)
- Billing and usage — token consumption and request volume across all workspaces
Models are managed at the organization level and granted to workspaces via entitlements.
Workspace
A project boundary within an organization. Workspaces provide isolation between teams or projects. Each workspace has:
- Apps — the AI applications you build and deploy
- Models — entitled models from the organization catalog
- Tools — external integrations (webhooks, MCP servers, REST APIs)
- Sources — knowledge bases and document collections
- Environments — pre-configured runtime environments (Production, Staging, Development)
App
The primary unit of work. An app contains everything needed to build, test, and deploy an AI workflow. When you open an app, you see these tabs:
| Tab | Purpose |
|---|---|
| Dashboard | Overview of app activity and status |
| Namespaces | Isolated data partitions for threads, memory, and artifacts |
| Augmentations | Pipeline definitions — stages, steps, and execution logic |
| Environments | Per-environment deployment status and active releases |
| Tokens | API keys for authenticating requests to this app's endpoints |
| Releases | Versioned snapshots ready for deployment |
| Settings | App configuration and metadata |
Core Building Blocks
How It All Connects
A typical workflow through the hierarchy:
- Your organization configures provider accounts and sets up the model catalog
- A workspace is created for your team, with model entitlements and environments
- You create an app and build augmentation pipelines with stages and steps
- Steps use models for inference, tools for external actions, and knowledge for context
- You create endpoints from the pipeline editor to expose pipelines as HTTP APIs
- When ready, you create a release with a version tag and deploy it to an environment
Change Tracking
Every change to pipelines, endpoints, and configuration is tracked as a commit with field-level diffs. The Change History timeline shows commits, releases, and deployments, letting you review and compare any point in your app's history.
Security Model
Access control follows the hierarchy:
- Organizations manage members, provider accounts, and billing
- Workspaces provide isolation boundaries between teams
- RBAC controls who can read, write, or manage each resource type within a workspace
- Vault provides KMS-backed secrets management for API keys and credentials, scoped to environments
See the Security concept page for details.