Smart Framework — Getting Started

// STEP 0

Prerequisites

Smart Framework targets teams building production web applications with a Node.js/TypeScript backend and a modern JavaScript frontend. Here's what you'll need.

Node.js

≥ 20.0.0 LTS

TypeScript

≥ 5.0

Package Manager

npm / yarn / pnpm

VS Code or JetBrains

IDE Extension required

Browser

Chrome / Firefox (Extension)

Database

PostgreSQL / MongoDB / MySQL

Framework experience: No prior framework experience is required beyond standard TypeScript/Node.js. In fact, developers with strong "traditional" framework habits sometimes need to unlearn patterns — because in Smart Framework, you'll never write authentication, authorization, logging, or concurrency code again, and that can feel disorienting at first.

// STEP 1

Installation

The Smart CLI scaffolds everything: project structure, core libraries, middleware configuration, and IDE Extension setup. One command.

Terminal

# Create a new Smart Framework project
$ npx smart-cli@latest init my-app


  ✦ Smart Framework Initializer v1.0.0
  ? Project name: my-app
  ? Database adapter: PostgreSQL
  ? Frontend target: React (modular)
  ? Install IDE Extension? Yes (VS Code detected)
  ? Install Browser Extension? Yes (Chrome detected)


  ✓ Core libraries installed (@smart/core, @smart/middleware, @smart/db)
  ✓ Frontend libraries installed (@smart/ui, @smart/client)
  ✓ Middleware layer configured
  ✓ Database adapter: @smart/db-postgres
  ✓ Ghost Protection: enabled (default)
  ✓ VS Code extension: smart-framework.vsix installed
  ✓ Browser extension: loaded at chrome://extensions
  ✓ Admin Control Panel: configured at port 3001


  Project ready. Start developing:
    cd my-app
    smart dev
          

Terminal — start the dev server

$ cd my-app && smart dev


  ✦ Smart Framework Dev Server
  ✓ Auth middleware:     active  (port 3000)
  ✓ Ghost Protection:   active  (embedded)
  ✓ Hot-swap server:    active  (port 3002)
  ✓ Admin Panel:        active  (port 3001)  →  http://localhost:3001
  ✓ App server:         active  (port 3000)  →  http://localhost:3000
  ✓ Database:           connected (PostgreSQL @ localhost:5432)
  ✓ Browser Extension:  connected (dev overlay ready)
  ✓ IDE Extension:      active (VS Code)


  Watching for changes. Build on save.
  Only changed components will rebuild.
          

Project structure after init

my-app/
├── src/
│   ├── handlers/          ← Your business logic. Only this.
│   │   └── users/
│   │       ├── getUser.handler.ts
│   │       └── updateUser.handler.ts
│   ├── domain/            ← Entities, value objects, domain rules
│   ├── components/        ← Standalone FE components (each builds independently)
│   └── skills/            ← AI Skills
├── smart.config.ts         ← Framework config (middleware, DB, auth provider)
├── smart.middleware.ts     ← Generated. Do not edit. Managed by framework.
└── package.json

Notice what's NOT here:
  ✗ No authMiddleware.ts
  ✗ No permissionGuard.ts
  ✗ No auditLogger.ts
  ✗ No concurrencyHandler.ts
  These don't exist. They don't need to.
          

// STEP 2

Onboarding Timeline

Here's what a typical developer journey looks like. These are real milestones, not marketing estimates.

HOURS 1–2 Setup

Environment Setup + Mental Model

Install the CLI, scaffold your first project, start the dev server, install the IDE + Browser extensions. Read the architecture overview. The key mental shift: your backend handlers contain only business logic. Everything else is handled automatically.

npx smart-cli init — project scaffolded and running
Admin Control Panel open and accessible
IDE Extension active — smart completions working
Browser Extension overlay visible in dev mode
Architecture overview read and understood

HOURS 2–4 First handler

Write Your First Handler — The "Wait, That's It?" Moment

Write your first CRUD handler. Notice it has no auth code. Notice it has no logging. Notice it's 8 lines. Run it. Watch the Browser Extension show you the full auth context, permission evaluation, and audit log entry that were created automatically. This is the moment it clicks.

First handler written — no authentication or authorization, no logging, pure logic
Browser Extension shows middleware execution trace
Admin Panel shows auto-generated audit log entry
Add a permission rule in Admin Panel — no deploy needed
Observe field stripped from response in real time

HOURS 4–8 Day 1

Build a Feature End-to-End

Build a complete feature: multiple handlers, a domain entity, a FE component, and permissions configured in the Admin Panel. Deploy the component standalone. Test Ghost Protection by opening the same record in two browser tabs and editing different fields concurrently.

3+ handlers written — all pure logic, all tested
Domain entity modeled with Smart DB context
FE component built as standalone unit
Component deployed independently with smart deploy
Ghost Protection tested with concurrent browser tabs
Permissions updated in Admin Panel without redeploying

DAY 2 Full velocity

Full Production Velocity

By day two, the patterns are natural. You write handlers without thinking about auth or logging. You update permissions live without opening a code editor. You deploy individual components without coordinating a release. The framework disappears and you're just building.

Handlers written at full speed — zero friction boilerplate
AI code generation producing clean Smart-compliant handlers
Deploying N times per day with zero release coordination
Non-engineers updating permissions independently in Admin Panel
Ghost Protection silently protecting all concurrent workflows

// STEP 3

Your First Handler

A Smart handler is a TypeScript async function that receives input, a SmartContext, and returns a result. That's all it is. Here's a complete example.

src/handlers/products/createProduct.handler.ts

import { SmartContext, SmartHandler } from '@smart/core'
import { Product, CreateProductInput } from '../../domain/Product'

// That's the entire handler. ~12 lines. 100% business logic.
// No auth. No logging. No race condition handling. No API version.

export const createProduct: SmartHandler = async (
  input: CreateProductInput,
  context: SmartContext
): Promise<Product> => {

  // Validate business rules (not auth — that's already done)
  if (input.price < 0) {
    throw new ValidationError('Price cannot be negative')
  }

  // Write to the data store via Smart context
  const product = await context.db.products().create({
    name:        input.name,
    price:       input.price,
    categoryId:  input.categoryId,
    createdBy:   context.principal.id   // identity from middleware
  })

  return product

  // By the time this return executes, Smart has already:
  // ✓ Validated user (stage 1)
  // ✓ Checked 'products:create' route permission (stage 2)
  // ✓ Stripped fields user cannot write, e.g. 'price' for junior role (stage 3)
  // ✓ Ghost Protection active on product record (stage 4)
  // ✓ Audit log written with before/after diff (stage 5)
  // ✓ Response field-filtered on egress (stage 6)
}
          

Type-safe context: The SmartContext object gives you context.principal (the authenticated user's identity and roles), context.db (type-safe data access), context.session, and context.request. It's everything you need — and nothing you don't (no auth functions, no logger, no lock manager).

// THE FREEDOM LIST

What you'll never
write again.

This is not a list of things Smart Framework does better. It's a list of things you will never touch in your backend code again — permanently, by architecture.

Never write again

User validation / token parsing
User session lookup or binding
Permission guard functions or decorators
Role check logic in handlers
Field-level permission checks
Nested field access control
Audit log create / write calls
Before/after diff computation
Optimistic or pessimistic locking
Race condition handlers
API version routing (v1, v2, v3)
Version migration scripts for clients
Full bundle rebuild scripts
Release coordination meetings

Focus 100% on

Business rules and domain logic
Data model design
Domain entities and value objects
Business validations (not authentication or authorization)
Workflow and process logic
Computation and transformation
Domain event handling
UI component behavior
User experience and flows
Integration with third-party services
Performance optimization
Feature development (all day, every day)
Tests (pure functions = trivial to test)
Shipping (N times per day if you want)

// API REFERENCE

The SmartContext API

Every handler receives a SmartContext as its second argument. This is your interface to everything the framework provides.

SmartContext — type definition

interface SmartContext {
  /** Authenticated principal — set by middleware stage 1 */
  principal: {
    id:      string
    roles:   string[]
    email:   string
    meta:    Record<string, unknown>
  }

  /** Type-safe data access — Ghost Protection built in */
  db: SmartDB           // context.db.users(), context.db.orders(), etc.

  /** Current request metadata */
  request: {
    id:          string   // unique request ID for tracing
    timestamp:   Date
    route:       string
    method:      string
  }

  /** Session — bound by middleware stage 1 */
  session: {
    id:      string
    startedAt: Date
  }

  /** Emit a domain event (for event-driven patterns) */
  emit: (event: string, payload: unknown) => void
}

// What's NOT on SmartContext (by design):
//   ✗ No auth() function — auth is done before you run
//   ✗ No checkPermission() — permissions checked in middleware
//   ✗ No logger — logging is automatic
//   ✗ No lock() / unlock() — Ghost Protection is automatic
          

// REFERENCE

Key concepts to understand

Before diving deep, these are the five concepts that will make everything else click.

SmartContext

The dependency injection object passed to every handler. Contains the authenticated principal, type-safe DB access, request metadata, and session. Does NOT contain authentication or authorization functions, logging utilities, or lock managers — those don't exist in your code. → See API reference above

Smart Middleware

The invisible six-stage pipeline that every request passes through before your handler runs: user validation, route permission check, field permission filter, Ghost Protection, audit log capture, and egress field filter. Configured once. Works everywhere. Never touched again. → Architecture deep dive

Ghost Protection

Field-level race condition prevention. When multiple users (or AI agents) edit the same record concurrently, Ghost Protection ensures non-conflicting field edits always succeed and true conflicts are surfaced — not silently overwritten. Zero code. Embedded in the data layer. → Full walkthrough on Features page

Standalone Components

Every FE component in Smart Framework is a standalone unit with its own build artifact. The build system only rebuilds what changed. Components are deployed independently to the CDN edge. End users hot-swap changed components with no page refresh. No monolithic bundles. → Build system comparison

Admin Control Panel

The live policy management interface. Route-level permissions, field-level permissions, and nested field permissions are all managed here. Changes take effect in milliseconds across all running instances with no code change, no deployment, no downtime. Full audit trail of policy changes included. → Auth deep dive

Smart Handlers

The core building block of your backend. A handler is a TypeScript async function that accepts input and a SmartContext and returns a typed result. It contains only business logic. The framework routes, validates, authorizes, and audits every handler call automatically. Handlers are trivially unit-testable because they are pure functions. → See first handler example above

// DEV TOOLING

Extensions that
make development a breeze.

Smart Framework ships two developer-experience extensions that bring the framework directly into your editing and browsing environment.

🧩

IDE Extension

VS Code · JetBrains

The IDE Extension gives your editor deep awareness of the Smart Framework. It knows your domain model, your handler signatures, and your policy configuration.

✓ Smart handler completions (no authentication or authorization code suggested)
✓ SmartContext API autocomplete
✓ Domain model type inference
✓ AI code generation (Smart-compliant output)
✓ Permission policy inline annotations
✓ One-click deploy from editor command palette

🔍

Browser Extension

Chrome · Firefox

The Browser Extension overlays framework context directly on your running app in dev mode. See what the middleware is doing in real time as you interact with your application.

✓ Live middleware execution trace per request
✓ Authentication & authorization stage result (pass/fail + reason)
✓ Permission policy evaluation (which fields stripped)
✓ Ghost Protection status (active sessions on record)
✓ Audit log entries in real time
✓ Hot-swap component inspector

Explore Architecture → All Features

Onboard in hours.Productive by day two.