Skip to main content

Introduction to Almadar

The Physics of Software: Natural Language → Schema → Production Application

What is Almadar?​

Almadar (المدار) is a declarative programming language for building full-stack applications. Instead of writing imperative code scattered across frontend and backend, you declare your application as a schema of:

  • Entities - Your data structures with persistence rules
  • Traits - Behavior defined as state machines
  • Pages - Routes with UI bindings

The Almadar compiler transforms this schema into a complete, production-ready application.

The Problem Almadar Solves​

Traditional Development​

Frontend Team          Backend Team          Database Team
     |                      |                      |
     v                      v                      v
  React Code    +     Express API    +      Schema/SQL
     |                      |                      |
     v                      v                      v
 Permissions   +    Permissions     +    Constraints
     |                      |                      |
     v                      v                      v
  Testing      +      Testing       +      Testing

Issues:

  • Business logic duplicated across layers
  • Permissions scattered in middleware, routes, and queries
  • Documentation separate from code
  • Testing requires multiple approaches

Almadar Development​

Almadar Schema (.orb file)
        |
        v
   almadar compile
        |
        v
Full-Stack Application
  - React Frontend
  - Express Backend  
  - Database Models
  - Permissions
  - Documentation

Benefits:

  • Single source of truth
  • Permissions in guards (one place)
  • Schema IS documentation
  • State machines are inherently testable

Key Concepts​

1. Entities​

Entities define what your application manages:

{
  "name": "Task",
  "persistence": "persistent",
  "fields": [
    { "name": "title", "type": "string", "required": true },
    { "name": "status", "type": "enum", "values": ["pending", "in_progress", "done"] },
    { "name": "assignee", "type": "relation", "target": "User" },
    { "name": "dueDate", "type": "date" }
  ]
}

2. Traits​

Traits define how your application behaves using state machines:

{
  "name": "TaskLifecycle",
  "stateMachine": {
    "states": [
      { "name": "Pending", "isInitial": true },
      { "name": "InProgress" },
      { "name": "Done" }
    ],
    "events": [
      { "key": "START", "name": "Start Working" },
      { "key": "COMPLETE", "name": "Mark Complete" }
    ]
  }
}

3. The Closed Circuit​

Every user action follows this path:

1. Event    → User clicks "Complete Task"
2. Guard    → Check: Is user the assignee?
3. Transition → State: InProgress → Done
4. Effects  → Server: Save to DB
             → Client: Show toast, refresh list
5. Response → UI updates with real data

Why "Almadar"?​

Almadar (المدار) means "orbit" in Arabic. Just as planets follow predictable paths governed by physical laws, applications built with Almadar follow predictable paths governed by state machines.

Next Steps​

  1. Install the CLI - Get Almadar on your system
  2. Contributing - Join the community

Ready to revolutionize how you build software? Let's go!