Flexurio No‑Code API Engine

1. What is Flexurio?
2. How it works
3. Quick start (SQLite)
4. Installation
5. Environment variables (.env)
6. Configuration layout (LOC_CONFIG)
7. Entity schema reference
8. Custom ID generation (function)
9. Hooks & validation
10. Formula placeholders
11. Endpoint reference
12. Authentication & authorization
13. Import & export
14. Column encryption
15. Logging & observability
16. Database feature flags (compile‑time)
17. Multi‑target build script (build.sh)
18. Troubleshooting
19. Security checklist
20. Contributing & license

Flexurio No‑Code API lets you stand up secure, multi‑database REST endpoints by describing each entity (table) in a JSON file. You write configuration, not code; the engine generates the HTTP surface, validates requests, talks to the database, and enforces authentication.

Typical use cases:

• Rapid prototyping of admin / data panels.
• Internal tooling and back‑office APIs.
• Putting a clean REST API over an existing MySQL / Postgres / SQLite / MSSQL / MongoDB database.
• Computed / formula‑driven flows and change‑capture journaling (PATCH & TRACE).

At startup the engine:

1. Reads the active config profile path from the LOC_CONFIG environment variable.
2. Loads enabled route names from LOC_CONFIG/routes.json.
3. Loads one entity schema per route from LOC_CONFIG/entity/<route>.json.
4. Ensures the core tables (flx_users, flx_roles) exist and seeds a default admin if none exists.
5. Registers a uniform REST surface for every route (only the HTTP methods you enable per schema).
6. Applies JWT authentication to all non‑public routes (with public overrides and an optional IP allow‑list).

                ┌────────────────────┐
   routes.json  │  enabled routes    │
                └─────────┬──────────┘
                          │  for each route
                          ▼
        LOC_CONFIG/entity/<route>.json  ──►  TableSchema
                          │
                          ▼
   ┌──────────────────────────────────────────────────────────┐
   │  Actix‑web router                                          │
   │   GET /<route>     POST /<route>    PUT /<route>/{id}      │
   │   DELETE /<route>/{id}   PATCH /<route>   TRACE /<route>   │
   │   POST /import/<route>   GET /export/<route>               │
   │   GET /validate/<route>  POST /generate/table/<route>      │
   └──────────────────────────────────────────────────────────┘
                          │
                          ▼
        DB adapter (MySQL · Postgres · SQLite · MSSQL · MongoDB)

The fastest way to try Flexurio — no external database needed.

# 1. Get a binary (build from source shown here; see §4 for installers)
cargo build --release

# 2. Create a minimal .env
cat > .env <<'EOF'
DB_TYPE=sqlite
SQLITE_URL=sqlite://data.db
LOC_CONFIG=config
SECRET_KEY=replace_with_a_long_random_secret
ENCRYPT_KEY=replace_with_another_random_secret
PORT=8080
REQUIRE_AUTH=True
DEBUG=True
LOGGING=True
EOF

# 3. Run it
./target/release/flx-nocode-api

On first start the engine creates flx_users / flx_roles if missing and, if there is no admin yet, prints a generated password to the console:

Your admin Password: 1234

Log in with email admin and that password (see §12).

• macOS or Linux (Windows works natively or via WSL).
• A database. SQLite needs nothing extra and is ideal for a first run.
• Rust toolchain only if you build from source.

curl -fsSL https://raw.githubusercontent.com/flexurio/flx-nocode-api/main/install-flexurio.sh | bash

The script detects your OS/architecture, downloads the matching asset from the latest GitHub release, installs the binary plus a convenient flexurio wrapper into ~/.local/bin, and adds it to your PATH. The flexurio command automatically reads the .env in the current working directory.

Reload your shell afterwards (e.g. source ~/.zshrc), then run flexurio from any folder containing a .env.

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass
.\install-flexurio.ps1
# open a new terminal, then:
flexurio

# macOS (Apple Silicon)
curl -fsSL -o flx-nocode-aarch64-apple-darwin.pkg \
  https://github.com/flexurio/flx-nocode-api/releases/latest/download/flx-nocode-aarch64-apple-darwin.pkg
sudo installer -pkg flx-nocode-aarch64-apple-darwin.pkg -target /

# Linux (x86_64)
curl -fsSL -o flx-nocode-x86_64-unknown-linux-gnu \
  https://github.com/flexurio/flx-nocode-api/releases/latest/download/flx-nocode-x86_64-unknown-linux-gnu
chmod +x flx-nocode-x86_64-unknown-linux-gnu
install -m 0755 flx-nocode-x86_64-unknown-linux-gnu "$HOME/.local/bin/flx-nocode"

git clone https://github.com/flexurio/flx-nocode-api.git
cd flx-nocode-api
cargo build --release
./target/release/flx-nocode-api

To build a smaller binary with only the database backend(s) you need, see §16.

docker-compose.yaml is included as a reference. Mount your static/, config/, and .env:

services:
  rust-app:
    build: .
    container_name: flx-nocode-api
    restart: always
    ports:
      - "2121:8080"        # access at http://localhost:2121
    volumes:
      - "./static:/app/static"
      - "./config:/app/config"
      - "./.env:/app/.env"

Copy the bundled example and edit it:

cp env .env

Pick exactly one DB_TYPE and its matching URL. Avoid duplicate keys.

Converter‑token mode is fail‑closed: if it is active and none of the verification variables are set, all converter‑token requests are rejected. See §12.

Logging runs on a non‑blocking background thread, so it never blocks the request path. In production prefer LOG_MIN_LEVEL=info (most SQL/param logs are at debug) and consider sampling under high load.

LOC_CONFIG/
  routes.json          # enabled routes + public routes
  rules.json           # (optional) role / endpoint authorization rules
  entity/
    <route>.json       # one schema per route — file name must match the route

Several sample profiles are included: config, config/example, config/pos, config/tms, configmftl.

{
  "routes": ["flx_users", "flx_roles", "banks", "bank_types"],
  "route_publics": ["login", "register"]
}

• routes — entities to expose. Each must have a matching entity/<name>.json.
• route_publics — routes reachable without a JWT.

1. Add the name to routes in routes.json.
2. Create entity/<route>.json (copy an existing one; ensure table and the file name align).
3. (Optional) POST /generate/table/<route> to create the physical table (requires auto_generate: true).
4. GET /validate/<route> to confirm the schema matches the database.
5. Use the CRUD endpoints.

Each entity/<route>.json deserializes into a TableSchema (see src/model.rs). Sections:

Each HTTP method is only registered when its section sets "enable_method": true.

{
  "name": "id",
  "type_data": "varchar(15)",
  "auto_increment": false,
  "nullable": false,
  "function": "{request.id_trans}/%Y/%m/000ID",
  "function_endpoint": "",
  "function_endpoint_path": "data",
  "encrypt": false,
  "default": null
}

The three function* fields work together to auto‑generate an id; they only apply to POST/insert:

• function — the format. Split on /; tokens like %Y/%m/%d (date), {request.field} (request value), and NNNID (zero‑padded running number) are resolved, everything else is literal.
• function_endpoint — where the running number comes from. Leave empty → the engine uses MAX(id)+1 for ids sharing the same prefix. Set it → the engine GETs that URL (with the built prefix appended as ?prefix=… and the request's Authorization header forwarded) and uses the returned number. There is no fallback: if the call fails the insert is aborted.
• function_endpoint_path — how to read the number out of the endpoint's JSON response (default data).

A column with no id generation simply sets "function": "" and omits the two endpoint fields. See §8 for worked examples.

"get": {
  "enable_method": true,
  "columns": ["banks.id", "banks.name", "bank_types.name"],
  "parameters": ["name.eq", "bank_type_id.eq"],
  "join_tables": [
    { "table": "bank_types", "columns": ["name"], "logical": "banks.bank_type_id = bank_types.id", "type_join": "left" }
  ],
  "column_groups": [],
  "having": [],
  "order_by": ["banks.id"],
  "where_clause": []
}

• parameters declares which query‑string filters are accepted, in the form column.operator (e.g. name.eq, created_at.gte). Clients then call GET /banks?name.eq=BCA.
• Pagination is controlled by LIMIT_DEFAULT / LIMIT_MAX.

Set function on a column (typically id) to build a formatted identifier on insert — e.g. SO/2026/01/0001. The pattern is split on / and each token is resolved:

Example pattern and the value it produces:

{ "name": "id", "type_data": "varchar(15)", "function": "{request.id_trans}/%Y/%m/000ID" }

request.id_trans = "SO"   →   SO/2026/01/0001

By default the …ID token is computed as MAX(id) + 1 for ids sharing the same prefix, inside the same transaction as the insert. You can instead fetch it from an external endpoint — useful when sequence numbers are owned by another service.

Add function_endpoint (and optionally function_endpoint_path) to the same column:

{
  "name": "id",
  "type_data": "varchar(15)",
  "function": "{request.id_trans}/%Y/%m/000ID",
  "function_endpoint": "http://localhost:8080/api/next-sequence",
  "function_endpoint_path": "data"
}

Behavior when function_endpoint is set:

1. The URL is interpolated ({request.field} placeholders are filled from the request body).
2. The already‑built prefix is appended as a query param, URL‑encoded — e.g. ?prefix=SO%2F2026%2F01 — so the endpoint can scope the sequence per prefix.
3. A GET is sent; the inbound request's Authorization header is forwarded.
4. The response must be JSON. The number is read from function_endpoint_path (dotted path, default data) and coerced to an integer.
5. The number is zero‑padded to the token width and spliced into the id.

Expected response shape (with the default path data):

{ "data": 1 }

→ produces SO/2026/01/0001.

No fallback: if the endpoint times out, returns a non‑2xx status, or the field is missing/non‑numeric, the insert is aborted with an error. Leave function_endpoint empty to use the built‑in MAX(id)+1 strategy.

Implementation: src/nocode/repositories/data_create_repo.rs (fetch_next_number_from_endpoint and query_next_number_from_max).

post, put, and del can run extra logic around the main database operation. All hook strings are prefixed to indicate their kind; an empty string or a value without a recognized prefix is ignored.

These are the actual field names the engine reads. (Older drafts of this README referred to before/after; those keys are not used.)

"post": {
  "enable_method": true,
  "pre_process":  "SQL:UPDATE counters SET val = val + 1 WHERE name = 'menus'",
  "post_process": "SQL:INSERT INTO audit_logs(entity, action, user_id) VALUES('menus','CREATE',{request.created_by_id})",
  "columns": ["name"]
}

• Placeholders are bound as parameters automatically (SQL‑injection safe) — you do not write ? yourself.
• Each hook is a single statement. For multi‑step transactional logic, use a stored procedure (patch.pre_process_sp) or DB triggers.
• pre_process / post_process run in the operation's transaction on SQL backends; validate_data runs first and can reject the request.

Call an external endpoint and assert on its response before allowing the write. Format:

API:<METHOD>:<URL>|<operator>:<response_path>:<request_path>

Example — only allow a role that the /roles endpoint returns:

"validate_data": "API:GET:http://127.0.0.1:8080/roles|in:data:request.role"

SQL: validation expects a query returning an is_valid boolean:

"validate_data": "SQL:SELECT CASE WHEN email NOT LIKE '%@%' THEN FALSE ELSE TRUE END AS is_valid FROM customers WHERE email = {request.email}"

The post.columns array lists the fields the POST endpoint accepts. To make a field mandatory, append a * to its name. The * is only a marker — the engine strips it and uses the real column name everywhere.

"post": {
  "enable_method": true,
  "columns": ["name*", "email*", "phone"]
}

Here name and email are required; phone is optional. A required field is rejected when it is absent, null, an empty string, or the literal string "null", returning:

400 Bad Request — Missing required field: name

Notes:

• A field is also treated as required (even without *) when its columns[] definition has "nullable": false and "auto_increment": false. The * suffix is the explicit way to enforce it for any column.
• Empty datetime/timestamp values ("" or "null") are coerced to SQL NULL before the required check runs.
• PUT (put.columns) uses the exact same * convention for updates.

Placeholders are available inside hooks and formula values:

Notes:

• For PUT, the path parameter /{id} is not auto‑injected into hooks — include id in the request body if a formula needs it.
• For POST with auto‑increment ids, the new id is not available via {request.*}. To reference it afterwards, use a custom id (columns[].function) or supply id yourself.
• Bindings are numeric/string‑inferred automatically. On PostgreSQL, ? placeholders are rewritten to $1, $2, … internally.

For a route <route> listed in routes.json (each method requires enable_method: true in its schema section):

Core / system endpoints:

curl -X POST http://localhost:8080/login \
  -H "Authorization: Basic $(printf 'admin:1234' | base64)"

• Credentials are passed via HTTP Basic auth (Basic base64(email:password)).
• Success returns a JWT with claims such as id, nm (name), rl (roles), and optional cs (custom claim from CUSTOME_JWT_QUERY).
• Send it on every protected request: Authorization: Bearer <token>.

The default admin (email admin) is seeded on first start; its generated password is printed to the console.

• Routes in route_publics (plus /login, /register) are public.
• All other routes require a valid Bearer token.
• IPs/CIDRs in WHITE_LIST_IP bypass token checks.
• Fine‑grained, role‑/endpoint‑based rules can be defined in LOC_CONFIG/rules.json (per‑method permission_id, allowed_fields, and if conditions such as $user.role / $user.id).

When routes.json defines a non‑default converter_token mapping, JWTs are issued by an external identity provider and Flexurio verifies their signature using the CONVERTER_JWT_* variables (§5). This is fail‑closed: with no verification key configured, converter‑token requests are rejected (unless CONVERTER_JWT_INSECURE_SKIP_VERIFY=true).

• Import — POST /import/<route> with a multipart file. CSV and XLSX are supported; column headers must match the entity's insertable columns. Rows are inserted in batches (IMPORT_BATCH_SIZE).
• Export — GET /export/<route>?type=csv|xlsx returns the route's data in the requested format (defaults to CSV; falls back to CSV if XLSX generation fails). The same filtering as GET /<route> applies.

Set "encrypt": true on a column to store its value encrypted at rest using ENCRYPT_KEY (AES‑GCM). The engine encrypts on write and decrypts on read transparently. Keep ENCRYPT_KEY secret and stable — rotating it requires re‑encrypting existing data.

• Structured logs cover endpoint registration and query execution; control verbosity with the LOG_*, DEBUG, and LOGGING variables (§5).
• GET /healthz for liveness/readiness probes.
• GET /metrics exposes Prometheus metrics.
• An audit trail is written to LOC_AUDIT.
• Logs and static assets are served under /static (e.g. GET /static/log/). Keep the audit log outside static/ so it is not publicly served.

Database backends are gated behind Cargo features so you can build a lean binary with only what you need.

[features]
default  = ["mysql", "postgres", "sqlite", "mssql", "mongodb"]
mysql    = ["sqlx/mysql", "sqlx/chrono"]
postgres = ["sqlx/postgres", "sqlx/chrono"]
sqlite   = ["sqlx/sqlite", "sqlx/chrono"]
mssql    = ["tiberius/chrono", "bb8"]
mongodb  = ["dep:mongodb"]

If you disable a backend but set DB_TYPE to it at runtime, the app exits with an error (e.g. mysql feature disabled).

# Only MySQL
cargo build --release --no-default-features --features mysql

# MySQL + SQLite
cargo build --release --no-default-features --features "mysql sqlite"

# Everything (default)
cargo build --release

# Build & run in one step
cargo run --release --no-default-features --features mysql

Smaller builds compile faster, produce smaller binaries, and remove unused code paths from production.

build.sh produces per‑database, per‑OS binaries with feature‑gated builds, and optionally signs/notarizes macOS artifacts when Apple credentials are present.

Use ./build.sh or bash build.sh (not sh build.sh) — macOS ships Bash 3.2.

./build.sh [--db <list>] [--os <list>] [--arch <list>] [--help]

• --db — mysql,postgres,sqlite,all (default all).
• --os — macos,windows,linux,all (default all).
• --arch — x86_64,aarch64,all (filters after OS expansion, default all).

OS group expansion:

• macos → x86_64-apple-darwin, aarch64-apple-darwin
• windows → x86_64-pc-windows-gnu
• linux → x86_64-unknown-linux-gnu, aarch64-unknown-linux-gnu

Examples:

./build.sh                                   # all DBs, all OS targets
./build.sh --db mysql                        # MySQL only, all OS
./build.sh --db mysql,sqlite --os macos      # MySQL + SQLite for macOS (both arches)
./build.sh --db postgres --os macos --arch aarch64
./build.sh --db mysql --os windows,linux --arch x86_64

Artifacts land in release/ as flx-nocode-<driver>-<target> (Windows adds .exe; signed macOS produces .pkg). With --db all (default) a single combined multi‑driver binary is emitted per target as flx-nocode-<target> for installer compatibility.

For each driver the script runs cargo build --release --target <triple> --no-default-features --features <driver>. macOS signing/notarization activates when APPLE_ID, APPLE_TEAM_ID, an app‑specific password, APPLE_IDENTITY, APPLE_IDENTITY_INS, PRIMARY_BUNDLE_ID, and KEYCHAIN_PROFILE are set; otherwise it just copies the binary.

• Use long, random SECRET_KEY and ENCRYPT_KEY; keep them out of version control.
• Rotate keys periodically (reissue tokens; re‑encrypt data if ENCRYPT_KEY changes).
• Grant the database user least privilege.
• Keep the audit log (LOC_AUDIT) outside the publicly served static/ directory.
• Terminate TLS at a reverse proxy (nginx / traefik / Caddy).
• In converter‑token mode, always configure signature verification — avoid CONVERTER_JWT_INSECURE_SKIP_VERIFY=true in production.
• Validate any externally‑supplied formula inputs.

Contributing

1. Fork and branch (feat/<name>).
2. Make focused commits; keep example configs valid.
3. Run cargo build / cargo test.
4. Open a PR with a clear description and test notes.

License — see LICENSE (and LICENSE-AGPL).

Credits — Flexurio Engineering Team. Built with Rust + Actix Web.