Miolo Application Architecture

This skill defines the standard architecture for miolo applications based on miolo-sample, the reference implementation for miolo apps.

Project Structure Overview

code

miolo-app/
├── package.json          # npm scripts and dependencies
├── .env                  # Development environment variables
├── .env.production       # Production environment variables  
├── .editorconfig         # Editor configuration
├── .gitignore           # Git ignore rules
├── components.json       # shadcn/ui configuration
├── jsconfig.json         # JavaScript/Import path configuration
├── eslint.config.js      # ESLint configuration
├── postcss.config.js     # PostCSS/Tailwind configuration
├── docker/               # Docker deployment configuration
├── db/                   # Database initialization (optional)
├── build/                # Production build output
├── src/                  # Source code
│   ├── cli/              # Client-side React application
│   ├── ns/               # Shared code (namespace)
│   ├── server/           # Backend server code
│   └── static/           # Static assets

Root Files

package.json Scripts

Standard npm scripts for miolo development and deployment:

json

{
  "scripts": {
    "reset": "rm -fr node_modules package-lock.json && npm i",
    "lint": "npx xeira lint src",
    "dev": "npx miolo dev",
    "deb": "npx miolo deb",
    "create-bin": "npx miolo create-bin",
    "build-client": "npx miolo build-client",
    "build-server": "npx miolo build-server",
    "build": "npm run build-client && npm run build-server && npm run create-bin",
    "start": "node ./build/server/run.mjs start",
    "stop": "node ./build/server/run.mjs stop",
    "restart": "node ./build/server/run.mjs restart"
  }
}

Key scripts:

•dev - Development mode with hot reload
•deb - Development mode with hot reload and debugging
•build - Complete production build
•start/stop/restart - Production server management

Import Aliases

Configure path aliases in package.json:

json

{
  "imports": {
    "#cli/*": "./src/cli/*",
    "#ns/*": "./src/ns/*",
    "#server/*": "./src/server/*",
    "#static/*": "./src/static/*"
  }
}

Use these aliases consistently in imports: import Thing from '#server/routes/thing.mjs'

Environment Files

•.env - Development configuration (database, ports, session salt, etc.)
•.env.production - Production overrides

Directory Structure

docker/

Docker deployment configuration:

•docker-compose.yaml - Service orchestration
•Dockerfile - Container build instructions

db/ (optional)

Database initialization scripts:

•init.sh - Database creation and setup script
•sql/ - SQL migration files (executed in alphabetical order)

Not required for all apps, but recommended for PostgreSQL-based applications.

build/

Production build output (generated, not versioned):

•cli/ - Built client application
•server/ - Built server application

Created by npm run build, used in production deployment.

src/cli/

Client-side React application code. Fixed subdirectory structure:

code

src/cli/
├── App.jsx              # Root application component
├── entry-cli.jsx        # Client entry point
├── index.html           # HTML template
├── components/          # React components (shadcn/ui, custom)
│   ├── ui/              # shadcn/ui components
│   └── ...              # Custom components
├── config/              # Client configuration
├── context/             # React contexts (data, session, theme, ui)
│   ├── data/
│   ├── session/
│   ├── theme/
│   └── ui/
├── hooks/               # Custom React hooks
├── layout/              # Layout components (sidebar, nav, etc.)
├── lib/                 # Client utilities
└── pages/               # Page components
    ├── dash/            # Dashboard pages
    ├── offline/         # Unauthenticated pages (login, etc.)
    └── ...              # Feature-specific page directories

Rules:

•Respect the subdirectory structure
•Place new components in appropriate subdirectories
•Pages go in pages/, grouped by feature
•Reusable UI components in components/
•Contexts follow the established pattern (Context.jsx, Provider.jsx, useContext.mjs)

src/ns/

Shared code accessible from both client and server:

code

src/ns/
└── models/              # Data models
    ├── base/            # Base classes (BaseModel, BaseArray, etc.)
    └── ...              # Application-specific models

Use for code that needs to run in both environments.

src/server/

Backend server code. Semi-fixed subdirectory structure:

code

src/server/
├── server.mjs           # Server entry point
├── cache/               # Cache implementations
├── db/                  # Database layer
│   ├── io/              # Database I/O operations (queries)
│   │   ├── users/       # User-related queries
│   │   ├── todos/       # Example: todo queries
│   │   └── ...          # Feature-specific query directories
│   └── triggers/        # Database triggers
├── lib/                 # Server libraries
├── miolo/               # Miolo server configuration
│   ├── auth/            # Authentication strategies
│   ├── cache.mjs        # Cache configuration
│   ├── cron/            # Cron jobs
│   ├── db.mjs           # Database configuration
│   ├── http.mjs         # HTTP configuration
│   ├── index.mjs        # Main miolo config
│   ├── routes/          # Base route configuration
│   └── ssr/             # Server-side rendering
├── routes/              # API endpoints (developers add here)
│   ├── index.mjs        # Route registration
│   ├── users/           # User endpoints
│   └── ...              # Feature-specific route directories
└── utils/               # Server utilities

Rules:

•cache/, lib/, utils/, miolo/ are relatively fixed
•Developers add new API endpoints in routes/
•Database queries go in db/io/, organized by domain
•Each route directory contains endpoint handlers
•Register new routes in routes/index.mjs

Key pattern: When adding a new feature:

•Create queries in db/io/feature-name/
•Create route handlers in routes/feature-name/
•Register routes in routes/index.mjs

src/static/

Static assets:

code

src/static/
├── fonts/               # Custom fonts
├── img/                 # Images
│   ├── default/         # Default images (avatars, etc.)
│   └── ...
├── public/              # Public root files (favicon, robots.txt)
└── style/               # Global CSS

Development Workflow

•Create app: npx miolo create <app-name>
•Develop: npm run dev (hot reload on port from .env)
•Build: npm run build (creates production build/)
•Deploy: Use docker/ configuration or build/server/run.mjs

Best Practices

•Respect directory structure - Don't create new top-level directories without reason
•Use import aliases - Always use #cli/, #server/, etc. for imports
•Follow naming conventions - Use lowercase with hyphens for directories, camelCase for files
•Organize by feature - In routes/ and db/io/, group by domain/feature
•Keep server config in miolo/ - Don't modify unless necessary
•Use contexts for state - Follow established context patterns in cli/context/

Common Patterns

Adding a new feature:

code

1. Add database queries: src/server/db/io/myfeature/*.mjs
2. Add API routes: src/server/routes/myfeature/*.mjs
3. Register routes: src/server/routes/index.mjs
4. Add client pages: src/cli/pages/myfeature/*.jsx
5. Add components if needed: src/cli/components/myfeature/*.jsx

Adding authentication:

•Strategies in src/server/miolo/auth/
•Configure in src/server/miolo/index.mjs

Adding static assets:

•Images: src/static/img/
•Fonts: src/static/fonts/
•Root files: src/static/public/

Architecture created by `npx miolo create`

The miolo create command generates this structure automatically. Maintain it throughout development to ensure consistency with miolo conventions and compatibility with miolo tooling.

Miolo Application Architecture

Project Structure Overview

Root Files

package.json Scripts

Import Aliases

Environment Files

Directory Structure

docker/

db/ (optional)

build/

src/cli/

src/ns/

src/server/

src/static/

Development Workflow

Best Practices

Common Patterns

Architecture created by npx miolo create

Architecture created by `npx miolo create`