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)

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](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

```text
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

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

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

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

Recommended backend environment:

```env
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:

```text
GET /health
```

### Frontend service

Set the Railway root directory to:

```text
frontend
```

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

```text
Build command: npm run build
Start command: npm start
```

Set:

```env
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:

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