Metadata-Version: 2.4
Name: magnexisdb
Version: 0.1.0
Summary: MagnexisDB - a developer-first document database with realtime observability.
License: All rights reserved. Copyright Magnexis.
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.8.0
Requires-Dist: typer>=0.12.3
Requires-Dist: uvicorn>=0.30.0
Requires-Dist: websockets>=13.0
Dynamic: license-file

# MagnexisDB
<img src="assets/magnexis-logo.svg" alt="Magnexis logo" width="150" />

![License: All Rights Reserved](https://img.shields.io/badge/License-All%20Rights%20Reserved-c62828?style=for-the-badge&logo=bookstack&logoColor=white)
![Status: Private](https://img.shields.io/badge/Status-Private-6a1b9a?style=for-the-badge&logo=shield&logoColor=white)
![Python](https://img.shields.io/badge/Python-3.11%2B-3776AB?style=for-the-badge&logo=python&logoColor=FFD43B)
![FastAPI](https://img.shields.io/badge/FastAPI-Backend-009688?style=for-the-badge&logo=fastapi&logoColor=white)
![WebSockets](https://img.shields.io/badge/WebSockets-Live%20Streams-1565C0?style=for-the-badge&logo=socketdotio&logoColor=white)
![CLI](https://img.shields.io/badge/CLI-Typer%20Powered-F57C00?style=for-the-badge&logo=gnubash&logoColor=white)
![Railway](https://img.shields.io/badge/Deploy-Railway-0B0D0E?style=for-the-badge&logo=railway&logoColor=white)


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

## Backend architecture

```text
[ Rust Core ]
- storage engine
- indexing
- query execution
- time-travel system

        ↓ (FFI / IPC)

[ Python Layer (FastAPI) ]
- REST API
- WebSocket streams
- auth (later)
- query parsing

        ↓

[ CLI (Typer) ]
- magnexis query
- magnexis trace
- magnexis replay
```

The Python engine remains the active execution path today, while the Rust core is scaffolded under `rust/` and exposed through a shared runtime boundary so MagnexisDB can move toward Rust-backed execution without changing the API or CLI surfaces.

## 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](LICENSE) for the full terms.

## What changed

This repo now has a deployable split:

- `frontend`: React + Vite admin console, ready for Vercel
- `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
- `rust`: workspace for the emerging Magnexis execution core

## 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

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

## Local quick start

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

Frontend:

```bash
cd frontend
npm install
npm run dev
```

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

## Runtime modes

- Default mode is `python`, which uses the current Python storage and query engine.
- Set `MAGNEXISDB_ENGINE=rust-ipc` to expose Rust-core-oriented runtime metadata as the sidecar execution path matures.
- In `rust-ipc` mode, read-only `query`, `explain`, and `trace` now execute through the Rust core over stdio JSON IPC, while writes, recovery, and mutation flows remain on the Python engine.
- Use `magnexisdb architecture` or `magnexisdb doctor` to inspect the active backend layout and Rust workspace status.

## Deploy split

### Backend on Railway

Use the repo on Railway and start the backend with:

```bash
python -m backend.main
```

Recommended environment:

```env
MAGNEXISDB_DB_PATH=data/magnexis.db
MAGNEXISDB_ALLOWED_ORIGINS=https://your-vercel-frontend.vercel.app
MAGNEXISDB_LOG_LEVEL=info
MAGNEXISDB_VERSION=0.1.0
```

Health endpoint:

```text
GET /health
```

### Frontend on Vercel

Set the Vercel root directory to:

```text
frontend
```

Set:

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

## CLI surface

Local commands:

- `magnexisdb serve`
- `magnexisdb health`
- `magnexisdb doctor`
- `magnexisdb architecture`
- `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:

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

## Developer scripts

PowerShell helpers are in [scripts/dev.ps1](scripts/dev.ps1):

```powershell
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.
