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

# Shortform syntax is for LLMs
MyApplication -> main v1.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]
}

# Shortform syntax is for LLMs
UserController @ controllers/user.controller.ts:
  <- [User, CreateUserDto, UserService]
  -> [UserController]

# Classes and functions defined in this file
UserController <: BaseController
  => [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]
}

# Shortform syntax is for LLMs
UserService <: BaseService, IUserService
  => [findById, create, update, delete]

# Class methods are defined as functions
findById :: (id: string) => User
  "Finds a user by ID"
  ~> [validateId, queryDatabase]

create :: (data: CreateUserDto) => User
  "Creates a new user"
  <- CreateUserDto
  -> User
  ~> [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]
}

# Shortform syntax is for LLMs
# ClassFile with #: operator eliminates boilerplate
UserService #: src/services/user.ts <: BaseService, IUserService
  <- [User, CreateUserDto, Database, Logger]
  => [findById, create, update, delete]

# Much cleaner than separate file + class definitions:
# UserService @ src/services/user.ts: <- [...] -> [UserService]
# UserService <: BaseService, IUserService => [...]

# Another example
NotificationService #: src/services/notification.ts <: BaseService
  <- [EmailProvider, SmsProvider, Notification]
  => [sendEmail, sendSms, markAsRead]

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]
}

# Shortform syntax is for LLMs
validateEmail :: (email: string) => boolean
  "Validates email format"

# Function with DTO references
login :: (credentials: LoginDto) => AuthToken
  "Authenticates user and returns token"
  <- LoginDto
  -> AuthToken
  ~> [validateCredentials, generateToken]
  $< [JWT_SECRET]

# Function affecting UI
updateUserProfile :: (data: ProfileDto) => User
  "Updates user profile"
  <- ProfileDto
  -> User
  ~ [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
    }
  }
}

# Shortform syntax is for LLMs
BaseEntity % "Base entity with common fields"
  - id: string "Unique identifier"
  - createdAt: Date "Creation timestamp"
  - updatedAt: Date "Last update timestamp"

# DTO with optional fields
User % "User entity"
  - id: string "User ID"
  - email: string "Email address"
  - name: string "Full name"
  - role: UserRole "User role" (optional)
  - avatar: string "Avatar URL" (optional)

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]
}

# Shortform syntax is for LLMs
App &! "Main application component"
  > [Header, MainContent, Footer]

# Child components
Header & "Application header"
  < [App]
  > [Logo, Navigation, UserMenu]
  # Components affected by: [login, logout]

MainContent & "Main content area"
  < [App]
  > [Sidebar, ContentArea]

# Component affected by functions
UserProfile & "User profile display"
  < [ContentArea]
  # Components affected by: [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]
}

# Shortform syntax is for LLMs
UserServiceContainer ~ "Docker container for user service"

# Asset containing a program
APIGateway ~ "API Gateway application"
  >> GatewayProgram

# Multiple assets
WebApp ~ "Frontend React application"
  >> ReactApp

MobileApp ~ "React Native mobile app"
  >> MobileProgram

WorkerService ~ "Background job processor"
  >> 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[]"
}

# Shortform syntax is for LLMs
API_VERSION ! config.ts : string
MAX_RETRIES ! config.ts : number
DEFAULT_TIMEOUT ! config.ts : number

# Object constants with schema
DATABASE_CONFIG ! database/config.ts : DatabaseConfig
FEATURE_FLAGS ! features.ts : FeatureFlags

# Array constants
ALLOWED_ORIGINS ! cors.config.ts : string[]
SUPPORTED_LOCALES ! i18n/config.ts : 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"
}

# Shortform syntax is for LLMs
DATABASE_URL $env "Database connection string" (required)
PORT $env "Server port"
  = "3000"
NODE_ENV $env "Environment mode"
  = "development"

# IAM/Security parameters
AWS_ROLE_ARN $iam "AWS role for service" (required)
SERVICE_ACCOUNT $iam "GCP service account"

# Runtime configuration
MAX_WORKERS $runtime "Maximum worker threads"
  = "4"
MEMORY_LIMIT $runtime "Memory limit in MB"

# Config file parameters
FEATURE_FLAGS $config "Feature toggle configuration"
API_RATE_LIMITS $config "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"]
}

# Shortform syntax is for LLMs
axios ^ "HTTP client library" v3.0.0
express ^ "Web framework" v4.18.0
lodash ^ "Utility library"

# Scoped packages
@types/node ^ "Node.js type definitions" v20.0.0
@aws-sdk/client-s3 ^ "AWS S3 client" v3.400.0

# Referenced in files
ServerMain @ src/server.ts:
  <- [express^, axios^]
  -> [startServer]

# Dependencies are marked with ^ in imports
start :: () => void
  "Starts the server"
  ~> [express^.listen]

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"]
}

# Shortform syntax is for LLMs
@import "./shared/models.tmd" as models
@import "./shared/services.tmd" as services
@import "./auth/auth.tmd" as auth

MyApp -> api v1.0.0

# Reference imported entities
UserAPI @ api.ts:
  <- [models.User, services.UserService]
  -> [UserAPI]

getUser :: (id: string) => models.User
  "Retrieves user by ID"
  ~> [services.findUser, auth.checkPermissions]

Getting Started

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

Create Your First .tmd File

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

# Longform syntax is for humans
program MyFirstApp {
  entryPoint: 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]
}

# Shortform syntax is for LLMs
MyFirstApp -> main v1.0.0

main @ main.ts:
  -> [App]

App <: Application
  => [start, stop]

start :: () => void
  "Starts the application"
  ~> [initialize, listen]
  $< [PORT, NODE_ENV]

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:
✅ my-app.tmd - Valid
   Program: MyFirstApp v1.0.0
   Files: 1, Classes: 1, Functions: 2

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

# For more options
typed-mind --help

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.

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]
}

# Shortform syntax is for LLMs
# Define your data models
User % "User entity"
  - id: string "Unique identifier"
  - name: string "Full name"
  - email: string "Email address"

# Add service classes
UserService <: BaseService
  => [getUser, createUser, updateUser]

getUser :: (id: string) => User
  "Retrieves a user by ID"
  -> User
  ~> [validateId, queryDatabase]

TypedMind

Why TypedMind?

LLM-Optimized

Bidirectional Validation

Import System

Concise Syntax

VS Code Extension

ClassFile Fusion

Modern Patterns

Syntax Guide

Program

File

Class

ClassFile

Function

Data Transfer Object (DTO)

UI Component

Asset

Constants

RunParameter

Dependency

Import System

Interactive Playground

Getting Started

Install the CLI

Create Your First .tmd File

Use the CLI to Check Your Architecture

Use with Your LLM

Install the VS Code Extension