MagnexisDB

MagnexisDB is a production-oriented document database built for developer experience, realtime updates, and transparent observability created by Magnexis.

Proprietary status

This repository is proprietary Magnexis software.

• External contributions are not being accepted.
• This is not an open contribution project.
• All rights are reserved by Magnexis.

See LICENSE for the full terms.

What changed

This repo now has a Railway deployable split:

• frontend: React + Vite admin console, deployable as a Railway frontend service
• backend: Railway-ready FastAPI service entrypoint
• api, core, models, realtime, utils: shared database engine and HTTP surface
• cli: expanded operator CLI with local, remote, and release-oriented commands

Highlights

• JSON document storage with nested fields and dynamic schemas
• Query engine with equality, comparison, inclusion, sorting, and pagination
• Field indexes backed by SQLite persistence and WAL durability
• FastAPI HTTP API plus WebSocket live collection streams
• React operator console for collections, queries, tracing, and insights
• Typer CLI for local administration, remote calls, streaming, and release metadata
• Query Replay and Smart Query Insights built in
• Snapshot export, snapshot import, operation-log recovery replay, and collection introspection
• Mongo-like find, findOne, insertOne, updateOne, replaceOne, deleteOne, countDocuments
• Mongo-like insertMany, updateMany, deleteMany, aggregation pipelines, $lookup, $facet, $bucket, and array filters
• Built-in execution tracing, natural query language, zero-setup sync import/deploy, and REST-style collection endpoints

Monorepo layout

MagnexisDB/
|-- backend/          # Railway entrypoint and env config
|-- frontend/         # React operator console for Railway
|-- api/              # FastAPI routes and app factory
|-- cli/              # Typer CLI
|-- core/             # storage, query engine, indexes, orchestration
|-- models/           # request/response models
|-- realtime/         # subscription hub
|-- assets/           # shared Magnexis branding
|-- scripts/          # smoke and release helpers
`-- packaging/        # PyInstaller spec for CLI artifacts

Local quick start

python -m venv .venv
.venv\Scripts\activate
pip install -e .
magnexisdb serve --host 127.0.0.1 --port 8000

Frontend:

cd frontend
npm install
npm run dev

Set VITE_MAGNEXISDB_API_URL if your backend is not on http://127.0.0.1:8000.

Railway deployment

Deploy the repository as two Railway services: one for the FastAPI backend and one for the Vite frontend.

Backend service

Set the Railway root directory to the repository root. The root railway.json provides this start command:

python -m backend.main

Recommended backend environment:

MAGNEXISDB_DB_PATH=data/magnexis.db
MAGNEXISDB_ALLOWED_ORIGINS=https://your-railway-frontend.up.railway.app
MAGNEXISDB_LOG_LEVEL=info
MAGNEXISDB_VERSION=0.1.0

Health endpoint:

GET /health

Frontend service

Set the Railway root directory to:

frontend

The frontend service uses the start script in frontend/package.json:

Build command: npm run build
Start command: npm start

Set:

VITE_MAGNEXISDB_API_URL=https://your-railway-backend.up.railway.app

CLI surface

Local commands:

• magnexisdb serve
• magnexisdb health
• magnexisdb doctor
• magnexisdb create-collection users
• magnexisdb list-indexes users
• magnexisdb describe users
• magnexisdb insert users "{\"name\":\"John\"}"
• magnexisdb query users --filter "{\"age\":{\"$gt\":18}}"
• magnexisdb explain .\query.json
• magnexisdb trace .\query.json
• magnexisdb profile-query .\query.json
• magnexisdb watch users --filter "{\"status\":\"active\"}"
• magnexisdb shell
• magnexisdb release-manifest

Remote commands:

• magnexisdb remote health --url https://your-backend
• magnexisdb remote collections --url https://your-backend
• magnexisdb remote query .\query.json --url https://your-backend
• magnexisdb remote explain .\query.json --url https://your-backend
• magnexisdb remote trace .\query.json --url https://your-backend
• magnexisdb remote insert users "{\"name\":\"John\"}" --url https://your-backend

Release artifacts

The repo now includes:

• packaging/magnexisdb-cli.spec for PyInstaller
• scripts/build_release.py for local wheel + binary builds
• .github/workflows/release-cli.yml for cross-platform CLI release artifacts

Local build:

python -m pip install build pyinstaller
python scripts/build_release.py

Developer scripts

PowerShell helpers are in scripts/dev.ps1:

powershell -ExecutionPolicy Bypass -File .\scripts\dev.ps1 install
powershell -ExecutionPolicy Bypass -File .\scripts\dev.ps1 start
powershell -ExecutionPolicy Bypass -File .\scripts\dev.ps1 smoke

Validation

• powershell -ExecutionPolicy Bypass -File .\scripts\dev.ps1 smoke
• python -m compileall api backend cli core models realtime utils scripts
• npm run build from frontend

Mongo-like behavior

MagnexisDB supports a familiar subset of MongoDB-style operators:

• query: $and, $or, $nor, $not, $eq, $ne, $gt, $gte, $lt, $lte, $in, $nin, $exists, $regex, $elemMatch
• update: $set, $unset, $inc, $push
• bulk: insertMany, updateMany, deleteMany
• single-write parity: replaceOne, deleteOne, countDocuments, upsert
• array-filtered updates: arrayFilters
• aggregation stages: $match, $sort, $sortByCount, $skip, $limit, $project, $group, $unwind, $addFields, $count, $lookup, $facet, $bucket
• group accumulators: $sum, $avg, $min, $max, $first, $last
• expression helpers: $concat, $add, $subtract, $setUnion

API docs are available at /docs.

License

Copyright Magnexis. All rights reserved.

No license is granted for public use, redistribution, modification, or contribution without prior written permission from Magnexis.