// architecture dsl

TypedMind

The Architecture DSL Designed for LLMs

Express complex software architectures in a concise, LLM-friendly syntax with bidirectional validation

Get Started Try Playground 
# Longform syntax is for humans
program TodoApp {
  entry: api
  version: "1.0.0"
}

file api {
  path: "api.ts"
  imports: [CreateTodoDto, Todo]
  exports: [TodoService]
}

class TodoService {
  extends: BaseService
  methods: [createTodo, getTodos]
}

function createTodo {
  signature: "(input: CreateTodoDto) => Todo"
  description: "Creates a new todo item"
  input: CreateTodoDto
  output: Todo
}

function getTodos {
  signature: "() => Todo[]"
  description: "Retrieves all todo items"
  output: Todo
}

dto CreateTodoDto {
  description: "Input for creating todos"
  fields: {
    title: {
      type: "string"
      description: "Todo title"
    }
    completed: {
      type: "boolean"
      description: "Completion status"
    }
  }
}

dto Todo {
  description: "Todo entity"
  fields: {
    id: {
      type: "string"
      description: "Unique identifier"
    }
    title: {
      type: "string"
      description: "Todo title"
    }
    completed: {
      type: "boolean"
      description: "Completion status"
    }
    createdAt: {
      type: "Date"
      description: "Creation timestamp"
    }
  }
}

Why TypedMind?

LLM-Optimized

Designed specifically for LLMs to understand and generate software architecture efficiently

Bidirectional Validation

Validates references in both directions, ensuring architectural consistency

Import System

Powerful import system with aliasing support for modular architecture definitions

Concise Syntax

Express complex architectures with minimal, readable syntax

VS Code Extension

Full IDE support with syntax highlighting, hover tooltips, and validation

ClassFile Fusion

New #: operator combines file and class definitions, eliminating naming conflicts and boilerplate

Modern Patterns

Supports classes, DTOs, UI components, assets, dependencies, and runtime parameters

Syntax Guide

Program

The root entity that contains all other entities in your architecture.

# Longform syntax is for humans
program MyApplication {
  entry: main
  version: "1.0.0"
}

# Import other TypedMind files
import "./shared/models.tmd" as models
import "./shared/services.tmd" as services

File

Represents a source code file in your architecture.

# Longform syntax is for humans
file UserController {
  path: "controllers/user.controller.ts"
  imports: [User, CreateUserDto, UserService]
  exports: [UserController]
}

class UserController {
  extends: BaseController
  methods: [getUser, createUser]
}

Class

Define classes with methods and relationships.

# Longform syntax is for humans
class UserService {
  extends: BaseService
  implements: [IUserService]
  methods: [findById, create, update, delete]
}

# Class methods are defined as functions
function findById {
  signature: "(id: string) => User"
  description: "Finds a user by ID"
  calls: [validateId, queryDatabase]
}

function create {
  signature: "(data: CreateUserDto) => User"
  description: "Creates a new user"
  input: CreateUserDto
  output: User
  calls: [validate, save]
}

ClassFile

Combines file and class definition using the fusion operator #: to prevent naming conflicts and reduce boilerplate.

# Longform syntax is for humans
# ClassFile combines file and class definition
UserService #: src/services/user.ts {
  extends: BaseService
  implements: [IUserService]
  methods: [findById, create, update, delete]
  imports: [User, CreateUserDto, Database, Logger]
}

# Eliminates the need for separate file definition
# Compare with traditional approach:
# file UserService { path: "src/services/user.ts", ... }
# class UserService { extends: BaseService, ... }

# Another example
NotificationService #: src/services/notification.ts {
  extends: BaseService
  methods: [sendEmail, sendSms, markAsRead]
  imports: [EmailProvider, SmsProvider, Notification]
}

Function

Standalone functions or class methods with parameters and return types.

# Longform syntax is for humans
function validateEmail {
  signature: "(email: string) => boolean"
  description: "Validates email format"
}

# Function with DTO references
function login {
  signature: "(credentials: LoginDto) => AuthToken"
  description: "Authenticates user and returns token"
  input: LoginDto
  output: AuthToken
  calls: [validateCredentials, generateToken]
  consumes: [JWT_SECRET]
}

# Function affecting UI
function updateUserProfile {
  signature: "(data: ProfileDto) => User"
  description: "Updates user profile"
  input: ProfileDto
  output: User
  affects: [ProfileComponent, HeaderComponent]
}

Data Transfer Object (DTO)

Define data structures with field descriptions.

# Longform syntax is for humans
dto BaseEntity {
  description: "Base entity with common fields"
  fields: {
    id: {
      type: "string"
      description: "Unique identifier"
    }
    createdAt: {
      type: "Date"
      description: "Creation timestamp"
    }
    updatedAt: {
      type: "Date"
      description: "Last update timestamp"
    }
  }
}

# DTO with optional fields
dto User {
  description: "User entity"
  fields: {
    id: {
      type: "string"
      description: "User ID"
    }
    email: {
      type: "string"
      description: "Email address"
    }
    name: {
      type: "string"
      description: "Full name"
    }
    role: {
      type: "UserRole"
      description: "User role"
      optional: true
    }
    avatar: {
      type: "string"
      description: "Avatar URL"
      optional: true
    }
  }
}

UI Component

Define UI components with containment relationships.

# Longform syntax is for humans
component App {
  root: true
  description: "Main application component"
  contains: [Header, MainContent, Footer]
}

# Child components
component Header {
  description: "Application header"
  containedBy: [App]
  contains: [Logo, Navigation, UserMenu]
  affectedBy: [login, logout]
}

component MainContent {
  description: "Main content area"
  containedBy: [App]
  contains: [Sidebar, ContentArea]
}

# Component affected by functions
component UserProfile {
  description: "User profile display"
  containedBy: [ContentArea]
  affectedBy: [updateUserProfile, deleteUser]
}

Asset

Define deployable assets like containers, packages, or applications.

# Longform syntax is for humans
asset UserServiceContainer {
  description: "Docker container for user service"
}

# Asset containing a program
asset APIGateway {
  description: "API Gateway application"
  contains: [GatewayProgram]
}

# Multiple assets
asset WebApp {
  description: "Frontend React application"
  contains: [ReactApp]
}

asset MobileApp {
  description: "React Native mobile app"
  contains: [MobileProgram]
}

asset WorkerService {
  description: "Background job processor"
  contains: [WorkerProgram]
}

Constants

Define constant values with file location and type.

# Longform syntax is for humans
constants API_VERSION {
  file: "config.ts"
  type: "string"
}

constants MAX_RETRIES {
  file: "config.ts"
  type: "number"
}

constants DEFAULT_TIMEOUT {
  file: "config.ts"
  type: "number"
}

# Object constants with schema
constants DATABASE_CONFIG {
  file: "database/config.ts"
  type: "DatabaseConfig"
}

constants FEATURE_FLAGS {
  file: "features.ts"
  type: "FeatureFlags"
}

# Array constants
constants ALLOWED_ORIGINS {
  file: "cors.config.ts"
  type: "string[]"
}

constants SUPPORTED_LOCALES {
  file: "i18n/config.ts"
  type: "Locale[]"
}

RunParameter

Define runtime parameters from different sources.

# Longform syntax is for humans
runparam DATABASE_URL {
  source: "env"
  description: "Database connection string"
  required: true
}

runparam PORT {
  source: "env"
  description: "Server port"
  default: "3000"
}

runparam NODE_ENV {
  source: "env"
  description: "Environment mode"
  default: "development"
}

# IAM/Security parameters
runparam AWS_ROLE_ARN {
  source: "iam"
  description: "AWS role for service"
  required: true
}

runparam SERVICE_ACCOUNT {
  source: "iam"
  description: "GCP service account"
}

# Runtime configuration
runparam MAX_WORKERS {
  source: "runtime"
  description: "Maximum worker threads"
  default: "4"
}

runparam MEMORY_LIMIT {
  source: "runtime"
  description: "Memory limit in MB"
}

# Config file parameters
runparam FEATURE_FLAGS {
  source: "config"
  description: "Feature toggle configuration"
}

runparam API_RATE_LIMITS {
  source: "config"
  description: "Rate limiting rules"
}

Dependency

Define external dependencies like npm packages with versions.

# Longform syntax is for humans
dependency axios {
  description: "HTTP client library"
  version: "3.0.0"
}

dependency express {
  description: "Web framework"
  version: "4.18.0"
}

dependency lodash {
  description: "Utility library"
}

# Scoped packages
dependency "@types/node" {
  description: "Node.js type definitions"
  version: "20.0.0"
}

dependency "@aws-sdk/client-s3" {
  description: "AWS S3 client"
  version: "3.400.0"
}

# Referenced in files
file ServerMain {
  path: "src/server.ts"
  imports: [express, axios]
  exports: [startServer]
}

# Dependencies are referenced in function calls
function start {
  signature: "() => void"
  description: "Starts the server"
  calls: ["express.listen"]
}

TypeDef

Named type aliases and enum declarations.

# Longform syntax
typedef StatusType {
  variant: enum
  members: [Active, Pending, Archived]
}

typedef UserId {
  variant: alias
  type: "string"
}

typedef Priority {
  variant: enum
  members: [Low, Medium, High, Critical]
}

Import System

Import entities from other TypedMind files with aliasing.

# Longform syntax is for humans
import "./shared/models.tmd" {
  alias: "models"
}

import "./shared/services.tmd" {
  alias: "services"
}

import "./auth/auth.tmd" {
  alias: "auth"
}

program MyApp {
  entry: api
  version: "1.0.0"
}

# Reference imported entities
file UserAPI {
  path: "api.ts"
  imports: ["models.User", "services.UserService"]
  exports: [UserAPI]
}

function getUser {
  signature: "(id: string) => models.User"
  description: "Retrieves user by ID"
  calls: ["services.findUser", "auth.checkPermissions"]
}

Interactive Playground

Try TypedMind syntax with full IDE support

Experience TypedMind with:

  • Monaco Editor with syntax highlighting
  • Real-time validation and error checking
  • IntelliSense and auto-completion
  • Shareable URLs for your code
  • AST visualization
Open Playground →

Getting Started

1

Install the CLI

Get the TypedMind command-line interface for validating and rendering your architecture files

npm install -g @sammons/typed-mind-cli

# Or with pnpm, yarn, or bun:
pnpm add -g @sammons/typed-mind-cli
yarn global add @sammons/typed-mind-cli
bun add -g @sammons/typed-mind-cli
2

Create Your First .tmd File

TypedMind files use the .tmd extension. Start with a simple program structure:

# Longform syntax is for humans
program MyFirstApp {
  entry: main
  version: "1.0.0"
}

file main {
  path: "main.ts"
  exports: [App]
}

class App {
  extends: Application
  methods: [start, stop]
}

function start {
  signature: () => void
  description: "Starts the application"
  calls: [initialize, listen]
  consumes: [PORT, NODE_ENV]
}
3

Use the CLI to Check Your Architecture

Validate your TypedMind files and visualize them with the CLI:

# Check for validation errors
typed-mind -c my-app.tmd

# Or use the short alias
tmd -c my-app.tmd

# Example output:
✓ No errors found!

# View your architecture as a diagram
typed-mind --render my-app.tmd

# For more options
typed-mind --help
4

Use with Your LLM

Share your .tmd files with LLMs for architecture discussions and code generation

Pro Tip: Have your LLM read the TypedMind Grammar Documentation to learn the complete syntax. TypedMind's concise syntax helps LLMs understand your entire architecture without token limitations.
5

Install the VS Code Extension

Get full IDE support with syntax highlighting, validation, and IntelliSense

# Longform syntax is for humans
# Define your data models
dto User {
  description: "User entity"
  fields: [
    { name: "id", type: "string", description: "Unique identifier" },
    { name: "name", type: "string", description: "Full name" },
    { name: "email", type: "string", description: "Email address" }
  ]
}

# Add service classes
class UserService {
  extends: BaseService
  methods: [getUser, createUser, updateUser]
}

function getUser {
  signature: (id: string) => User
  description: "Retrieves a user by ID"
  output: User
  calls: [validateId, queryDatabase]
}

Full Documentation

Project README

Overview, installation and getting started

Core Package README

@sammons/typed-mind parser and validator usage

Language Reference

Complete grammar reference for all TypedMind entities