{"id":34547377,"url":"https://github.com/sptlco/spatial","last_synced_at":"2026-05-04T23:02:22.986Z","repository":{"id":292424506,"uuid":"980731674","full_name":"sptlco/spatial","owner":"sptlco","description":"Open-source platform powering global operations.","archived":false,"fork":false,"pushed_at":"2026-04-27T20:56:01.000Z","size":3660,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-27T22:24:30.250Z","etag":null,"topics":["autonomous","cloud","compute","csharp","docker","dotnet","ecs","entity-component-system","ethereum","ilgpu","liquid-neural-networks","mongodb","neural-network","nextjs","platform","react","stripe","typescript","work-stealing"],"latest_commit_sha":null,"homepage":"https://sptlco.com","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/sptlco.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-05-09T16:05:48.000Z","updated_at":"2026-04-27T20:55:54.000Z","dependencies_parsed_at":"2025-07-19T07:21:43.839Z","dependency_job_id":"e766f2e0-76bb-47e6-b6a1-d3b1a779ed75","html_url":"https://github.com/sptlco/spatial","commit_stats":null,"previous_names":["cundiffd/spatial","sptlco/spatial"],"tags_count":317,"template":false,"template_full_name":null,"purl":"pkg:github/sptlco/spatial","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sptlco%2Fspatial","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sptlco%2Fspatial/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sptlco%2Fspatial/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sptlco%2Fspatial/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sptlco","download_url":"https://codeload.github.com/sptlco/spatial/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sptlco%2Fspatial/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32628211,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-04T10:08:07.713Z","status":"ssl_error","status_checked_at":"2026-05-04T10:08:02.005Z","response_time":58,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["autonomous","cloud","compute","csharp","docker","dotnet","ecs","entity-component-system","ethereum","ilgpu","liquid-neural-networks","mongodb","neural-network","nextjs","platform","react","stripe","typescript","work-stealing"],"created_at":"2025-12-24T07:28:39.129Z","updated_at":"2026-05-04T23:02:22.958Z","avatar_url":"https://github.com/sptlco.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"header.png\" alt=\"Spatial\" /\u003e\n  \u003cbr/\u003e\n  \u003cbr/\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://github.com/sptlco/spatial/actions/workflows/build.yml\"\u003e\u003cimg src=\"https://github.com/sptlco/spatial/actions/workflows/build.yml/badge.svg\" alt=\"Build\" /\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/github/license/sptlco/spatial\" alt=\"License\" /\u003e\u003c/a\u003e\n  \u003cbr/\u003e\n  \u003cbr/\u003e\n\u003c/p\u003e\n\nThis repository contains all official source code and documentation for [Spatial Corporation](https://sptlco.com) — including the public website, company blog, and the private platform powering its operations. At its core, Spatial (The Platform) is an autonomous, self-learning system that perceives its environment, reasons over time, and takes action, running continuously in the cloud.\n\n---\n\n| System                                            | Status        |\n| ------------------------------------------------- | ------------- |\n| Identity (users, roles, permissions, API keys)    | `working`     |\n| ECS simulation engine                             | `working`     |\n| Neural network (Hypersolver)                      | `working`     |\n| Compute scheduler                                 | `working`     |\n| Logistics — assets (Ethereum)                     | `working`     |\n| Logistics — shipments, orders, inventory (Stripe) | `in progress` |\n| TCP networking                                    | `working`     |\n| Web dashboard                                     | `in progress` |\n| Mobile app                                        | `in progress` |\n| Compute interface                                 | `planned`     |\n\n---\n\n## Requirements\n\n- [Docker](https://docs.docker.com/get-docker/) with the Compose plugin\n- [.NET 10 SDK](https://dotnet.microsoft.com/download) (development only)\n- [Node.js 20](https://nodejs.org/) (development only)\n\n## Getting started\n\nRun the setup script once to install the CLI:\n\n```bash\nbash scripts/setup.sh\n```\n\nThen deploy the full stack:\n\n```bash\nspatial deploy\n```\n\n## CLI\n\n```\nspatial deploy      Build and start all services\nspatial shutdown    Stop all services\nspatial redeploy    Rebuild and restart, then reload NGINX\nspatial develop     Run the cloud server in watch mode (hot reload)\nspatial status      Show running containers\nspatial logs        Tail logs from all services\n```\n\n## Services\n\n| Service | Description                                           |\n| ------- | ----------------------------------------------------- |\n| `cloud` | .NET 10 backend — ECS simulation, API, neural network |\n| `web`   | Next.js frontend — platform dashboard                 |\n| `mongo` | MongoDB 8 — primary data store                        |\n| `redis` | Redis 8 — caching and ephemeral state                 |\n| `nginx` | Reverse proxy — routes traffic, terminates TLS        |\n| `code`  | code-server — browser-based VS Code for development   |\n\n## Configuration\n\nThe cloud server uses layered ASP.NET configuration. Settings are merged in this order:\n\n1. `cloud/Server/appsettings.json` — base defaults\n2. `cloud/Server/appsettings.{Environment}.json` — environment overrides (`Development`, `Production`)\n3. `cloud/Server/appsettings.Override.json` — local secrets (not committed)\n\nCreate `appsettings.Override.json` and populate it before running:\n\n```json\n{\n  \"JWT\": {\n    \"Issuer\": \"https://your-domain.com\",\n    \"Audience\": \"https://your-domain.com\",\n    \"Secret\": \"\u003csigning-secret\u003e\"\n  },\n  \"Database\": {\n    \"ConnectionString\": \"mongodb://mongo:27017\",\n    \"Name\": \"spatial\"\n  },\n  \"Cache\": {\n    \"ConnectionString\": \"redis:6379\",\n    \"Database\": 0\n  },\n  \"Ethereum\": {\n    \"Endpoint\": \"https://mainnet.infura.io/v3/\u003capi-key\u003e\",\n    \"Key\": \"\u003cwallet-private-key\u003e\",\n    \"Allocator\": {\n      \"Exposure\": 0.0,\n      \"Bandwidth\": 0.0,\n      \"Minimum\": 0,\n      \"Deadline\": 0,\n      \"Tolerance\": 0.0\n    }\n  },\n  \"Stripe\": {\n    \"Key\": \"sk_live_...\"\n  },\n  \"SMTP\": {\n    \"Host\": \"mail.example.com\",\n    \"Port\": 587,\n    \"Name\": \"Spatial\",\n    \"Username\": \"system@example.com\",\n    \"Password\": \"\u003cpassword\u003e\"\n  }\n}\n```\n\n| Key                            | Description                                   |\n| ------------------------------ | --------------------------------------------- |\n| `JWT.Secret`                   | Signing secret for issued tokens              |\n| `Database.ConnectionString`    | MongoDB connection string                     |\n| `Cache.ConnectionString`       | Redis connection string                       |\n| `Ethereum.Endpoint`            | Ethereum RPC endpoint (e.g. Infura)           |\n| `Ethereum.Key`                 | Wallet private key used by the allocator      |\n| `Ethereum.Allocator.Exposure`  | Max fraction of holdings exposed per position |\n| `Ethereum.Allocator.Bandwidth` | Max fraction of holdings traded per tick      |\n| `Ethereum.Allocator.Minimum`   | Minimum trade size in USD                     |\n| `Ethereum.Allocator.Deadline`  | Trade execution deadline in seconds           |\n| `Ethereum.Allocator.Tolerance` | Slippage tolerance                            |\n| `Stripe.Key`                   | Stripe secret key for commerce operations     |\n| `SMTP.*`                       | Outbound mail credentials                     |\n\n### Web\n\nThe web interface is configured via `interface/web/.env`:\n\n```env\nNEXT_PUBLIC_SERVER_ENDPOINT=https://your-domain.com\nJWT_SECRET=\u003csame-secret-as-server\u003e\n```\n\n| Key                           | Description                                  |\n| ----------------------------- | -------------------------------------------- |\n| `NEXT_PUBLIC_SERVER_ENDPOINT` | URL of the cloud server API                  |\n| `JWT_SECRET`                  | Must match `JWT.Secret` in the server config |\n\n\nTo start the web development server, run the following:\n```bash\ncd interface\nnpm run dev:web\n```\n\n### NGINX\n\n`config/nginx/default.conf` is the NGINX virtual host configuration. Update the `server_name` directives to match your domain, and ensure the `ssl_certificate` and `ssl_certificate_key` paths point to your certificates:\n\n```\nconfig/nginx/ssl/certs/\u003cdomain\u003e.pem\nconfig/nginx/ssl/private/\u003cdomain\u003e.key\n```\n\nSSL certificates must be present before the `nginx` container will start. The recommended way to obtain them is with [Certbot](https://certbot.eff.org/), which is available on Linux, macOS, and Windows (via WSL 2):\n\n```bash\ncertbot certonly --standalone -d your-domain.com -d cloud.your-domain.com -d code.your-domain.com\n```\n\nOnce issued, place the certificate files at these paths:\n\n```\nconfig/nginx/ssl/certs/your-domain.com.pem   ← fullchain.pem\nconfig/nginx/ssl/private/your-domain.com.key  ← privkey.pem\n```\n\nThe default config expects three subdomains:\n\n| Subdomain               | Proxies to           |\n| ----------------------- | -------------------- |\n| `your-domain.com`       | `web` — public site  |\n| `cloud.your-domain.com` | `cloud` — API        |\n| `code.your-domain.com`  | `code` — code-server |\n\nIt is also recommended to restrict the `code` subdomain to your IP address in `default.conf`:\n\n```nginx\nserver {\n    listen 443 ssl http2;\n    server_name code.your-domain.com;\n\n    allow \u003cyour-ip\u003e;\n    deny all;\n\n    ...\n}\n```\n\n### code-server\n\n`config/code/config.yaml` configures the browser-based editor. Set a strong password before deploying:\n\n```yaml\nbind-addr: 0.0.0.0:8080\nauth: password\npassword: \u003cyour-password\u003e\ncert: false\n```\n\n## Architecture\n\n```\ninterface/\n  web/        Next.js app — public site, blog, and platform dashboard\n  mobile/     React Native app (Expo)\n\ncloud/\n  Core/       Foundation library (ECS, networking, identity, compute)\n  Server/     Cloud server (API, ECS systems, data models)\n  Generators/ Compile-time source generators for ECS types\n  Tests/      Unit tests\n  Performance/ Benchmarks\n```\n\n## Key systems\n\n### Neural network\n\nThe brain of the system. Neurons and synapses live as ECS entities and are updated each tick.\n\n| Neuron type | Role                                                                          |\n| ----------- | ----------------------------------------------------------------------------- |\n| Sensory     | Receives preprocessed feature vectors from external protocols                 |\n| Temporal    | Maintains time-dependent state via RK4 integration                            |\n| Command     | Smooths temporal dynamics into higher-level signals via exponential filtering |\n| Motor       | Emits output signals routed to protocol-specific Propagators                  |\n\nSynaptic weights evolve continuously using Hebbian plasticity modulated by spatial distance and activity. Learned state is flushed to MongoDB on shutdown and restored on startup.\n\nSignal flow: `Protocol → Sensory → Temporal → Command → Motor → Protocol`\n\nThe temporal dynamics are based on Liquid Time-constant (LTC) networks. See [references](#references) for the foundational papers.\n\n### ECS engine\n\nA custom high-performance Entity Component System (ECS).\n\n- Archetype-based chunk storage for cache-friendly iteration\n- Type-safe Queries, Signatures, and Futures via compile-time source generators\n- Parallel mutation via `Space.Mutate` with `Future` scheduling\n\n### Compute\n\nA custom job scheduler with work-stealing parallelism and GPU acceleration via [ILGPU](https://ilgpu.net/).\n\n- **Computer** — manages a pool of `Agent` workers, one per logical CPU core\n- **Agent** — each runs on a dedicated highest-priority thread and steals jobs from peers when idle (see [references](#references))\n- **Graph** — a DAG of jobs topologically sorted via Khan's algorithm before dispatch; cycles are detected and rejected\n- **Handle** — an awaitable completion token returned on dispatch\n\n| Job type           | Description                                                        |\n| ------------------ | ------------------------------------------------------------------ |\n| `CommandJob`       | A single callable with configurable timeout                        |\n| `ParallelForJob`   | Splits an iteration range into batches distributed across agents   |\n| `ParallelFor2DJob` | Same, over a 2D index space                                        |\n| `KernelJob`        | GPU-accelerated kernel; targets CUDA, OpenCL, or CPU automatically |\n\nA web interface for submitting and monitoring compute jobs is planned.\n\n### Identity\n\nFull role-based access control.\n\n- JWT sessions with custom claims enrichment\n- Users, accounts, roles, permissions, scopes, and API keys\n- Assignments bind roles to principals with optional scope restrictions\n\n### Logistics\n\nThe logistics module covers two distinct areas:\n\n**Assets** track the configured wallet's Ethereum holdings. The dashboard shows current balance, transaction count, total volume (USD), gas costs, and performance over configurable time windows (24h, 7d, 30d, 1y). Transactions are executed autonomously to maintain the configured exposure (by swapping stable coin `USDC` for `ETH` and vice versa).\n\n**Shipments, orders, and inventory** are Stripe-based commerce operations — physical goods, fulfillment, and sales management. The dashboard provides a searchable, filterable shipment list with origin and destination details. Order tracking and inventory management are in progress.\n\n### TCP networking\n\nA custom binary protocol for native client communication.\n\n- Packets are framed with a variable-length prefix (1 or 3 bytes)\n- Payloads are encrypted with a seeded XOR cipher established via handshake\n- `NETCOMMAND` identifies message types; `ProtocolBuffer` handles serialization\n\n\u003e The networking layer is inspired by the protocol design of [Fiesta Online](https://en.wikipedia.org/wiki/Fiesta_Online), and originally powered a server emulator for that game.\n\n## Stack\n\n| Layer    | Technology                        |\n| -------- | --------------------------------- |\n| Backend  | C# / .NET 10, ASP.NET Core        |\n| Database | MongoDB 8, Redis 8                |\n| Ethereum | Nethereum                         |\n| Payments | Stripe                            |\n| Logging  | Serilog                           |\n| Web      | Next.js, TypeScript, Tailwind CSS |\n| Mobile   | React Native, Expo                |\n\n## Contributing\n\nContributions are appreciated!\\\nAll changes to this repository require a pull request. Direct pushes to `main` are not permitted.\\\nSee the [backlog](https://github.com/orgs/sptlco/projects/1) for current issues.\n\n### Workflows\n\n| Workflow    | Trigger              | What it does                                                                     |\n| ----------- | -------------------- | -------------------------------------------------------------------------------- |\n| Build       | Push to any branch   | Restores, builds, and runs tests                                                 |\n| Performance | PR or push to `main` | Runs benchmarks and uploads results as artifacts (retained for 90 days)          |\n| Release     | Push to `main`       | Creates a release via release-please, then deploys to production (upon approval) |\n| Publish     | Version tag          | Publishes packages to GitHub Packages                                            |\n\nBenchmark results are attached to each workflow run and can be compared across PRs to catch regressions before they land.\n\n### Deployment\n\nMerging to `main` triggers an automatic deployment to **West US** ([sptlco.com](https://sptlco.com)) via SSH once release-please determines a release is warranted.\n\n### Packages\n\nThe following packages are published to GitHub Packages on release:\n\n| Package                | Description                                       |\n| ---------------------- | ------------------------------------------------- |\n| `Spatial` (NuGet)      | Core library — ECS, compute, networking, identity |\n| `@sptlco/client` (npm) | API client for the web and mobile interfaces      |\n| `@sptlco/data` (npm)   | Shared data types and schemas                     |\n| `@sptlco/design` (npm) | Design system and component library               |\n\n## References\n\n- Hasani, R., et al. — [Liquid Time-constant Recurrent Neural Networks as Universal Approximators](https://arxiv.org/pdf/1811.00321)\n- Hasani, R., et al. — [Liquid Time-constant Networks](https://arxiv.org/pdf/2006.04439)\n- Chase Latta — [Liquid Neural Networks](https://www.youtube.com/watch?v=IlliqYiRhMU\u0026t=1970s) (lecture)\n- D. Chase, D. Lev — [Dynamic Circular Work-Stealing Deque](https://www.dre.vanderbilt.edu/~schmidt/PDF/work-stealing-dequeue.pdf)\n\nFor a discussion of how these ideas are applied in this codebase, see [Notes on Temporal ECS Neural Dynamics](https://dakarai.org/blog/post/temporal-ecs-neural-dynamics).\n\n## License\n\n\u0026copy; Spatial Corporation. See [LICENSE](LICENSE) for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsptlco%2Fspatial","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsptlco%2Fspatial","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsptlco%2Fspatial/lists"}