A.I.N.D.Y.

A.I.N.D.Y. is a Python/FastAPI runtime and application platform for memory operations, flow execution, Nodus script execution, agent runs, scheduling, and domain application orchestration.

This repository is archived as historical reference.

It is not the primary active development or deployment repo.

Use these repos instead:

• C:\dev\aindy-runtime for runtime code, runtime packaging, runtime-only boot, runtime deployment docs, and runtime CI
• C:\dev\aindy-apps-monolith for apps/, client/, aindy_plugins.json, alembic/, app-profile docs, and app-profile tests

For the full cutover note, use ARCHIVE_STATUS.md.

Split-repo status:

• C:\dev\aindy-runtime is now the runtime deployment and packaging source of truth
• C:\dev\aindy-apps-monolith is now the app deployment source of truth for apps/, aindy_plugins.json, alembic/, and client/
• this combined repo remains a historical, migration, and comparison workspace; it is no longer the primary operational source of truth for extracted-repo deployment

The repository is a modular monolith in transition:

• one deployable backend/runtime
• multiple domain apps under apps/
• shared runtime/platform code under AINDY/
• one React client under client/

This README is intentionally engineering-focused. It describes the repository as it exists today, not the historical product pitch or an aspirational future architecture.

Backend/runtime:

• AINDY/ - runtime, platform layer, routes, memory, scheduler, agents, worker entrypoints
• apps/ - domain apps registered into the runtime via bootstrap/registry wiring
• alembic/ - SQL schema migrations
• tests/ - unit, API, and system coverage

Frontend:

• client/ - React/Vite client

Operational/docs:

• docs/ - current documentation
• docker-compose.yml - local/dev container stack
• server.js - optional Node gateway/bridge

At a high level:

React/Vite client
    |
    v
FastAPI app (AINDY/main.py)
    |
    +-- runtime/platform layers in AINDY/
    +-- domain apps in apps/
    +-- PostgreSQL primary state
    +-- MongoDB for Mongo-backed features
    +-- Redis for distributed execution / event bus / shared cache semantics

Important boundaries:

• AINDY/ owns runtime and platform behavior.
• apps/ owns domain behavior and registers into the runtime.
• The system is still one deployment unit, not a set of independently deployable services.
• platform boot is registry-driven rather than hardcoded per-domain inside AINDY/
• platform full operation still depends on app-owned routes, tools, flows, and some models
• agent lifecycle persistence now lives in AINDY/db/models/ as runtime-owned infrastructure
• current transitional coupling is narrower and no longer includes AINDY/ -> apps.agent.models.* imports
• target architecture is no direct runtime-to-app imports, with cross-domain access through registries, syscalls, and public contracts

Supported and actively implemented:

• authenticated API access with JWT and platform API keys
• memory read/write/recall operations
• flow registration and flow execution
• Nodus script execution, scheduling, and trace lookup
• agent runs and agent observability
• task, analytics, ARM, masterplan, search, social, identity, rippletrace, and other domain workflows through the monolith
• health, readiness, scheduler, and observability surfaces

Do not assume from this that every surface is equally mature or equally production-safe.

Reasonably supported today:

• single-instance deployment with PostgreSQL and the required app configuration
• limited multi-instance deployment when Redis is configured and separate workers are used where required
• lease-gated scheduler leadership
• readiness checks that reflect required runtime expectations
• dynamic registry restore and restart rehydration paths
• degraded startup for explicitly peripheral domains after the app bootstrap plugin has loaded successfully
• explicit runtime-only startup through uvicorn AINDY.runtime_only:app or AINDY_BOOT_MODE=runtime-only

Still transitional:

• overall app/runtime boundary cleanup across the full repo
• some legacy or mixed route surfaces preserved for compatibility
• limited multi-instance behavior rather than fully general horizontal scale
• some process-local state and per-instance limits that are acceptable today but not globally coordinated
• mixed Postgres/Mongo operational behavior depending on the feature surface in use
• optional Node gateway path that is not the core backend entrypoint

For deployment guidance, use the deployment docs rather than inferring from old README text.

Boot safety note:

• runtime-only is the supported no-app runtime mode and resolves to the platform-only boot profile.
• The default app profile is strict: if apps.bootstrap or another requested plugin module is missing or broken, startup now fails instead of silently falling back to a partial runtime.
• The exact supported no-app surface is defined in docs/runtime/RUNTIME_ONLY_DEPLOYMENT.md.

Prerequisites:

• Python 3.10+
• Node.js 18+
• PostgreSQL
• MongoDB if you need Mongo-backed features
• Redis if you need distributed execution, shared cache semantics, or limited multi-instance deployment

Docker quickstart:

docker compose up

This quickstart runs the API in EXECUTION_MODE=thread, so no worker is required. If you want distributed execution, Redis, and a worker process, use the full Compose profile and the production/deployment guidance in docs/deployment/RUNNING_IN_PRODUCTION.md.

Backend:

alembic upgrade head
uvicorn AINDY.main:app --reload

Runtime-only backend:

alembic upgrade head
uvicorn AINDY.runtime_only:app --reload

Frontend:

cd client
npm run dev

Default local URLs:

• backend: http://127.0.0.1:8000
• frontend: http://localhost:5173

For production deployment, environment requirements, worker setup, and multi-instance checks, use docs/deployment/RUNNING_IN_PRODUCTION.md.

AINDY/               Runtime, platform, routes, worker, memory, agents
apps/                Domain apps registered into the runtime
client/              React/Vite frontend
docs/                Engineering and operator documentation
alembic/             Database migrations
tests/               Unit, API, and system tests
server.js            Optional Node gateway

Use docs/deployment/DEPLOYMENT_MODEL.md as the source of truth for:

• supported single-instance deployment
• limited multi-instance deployment
• API/worker process expectations
• Redis, PostgreSQL, and Mongo requirements
• scheduler leadership behavior
• degraded-mode expectations

Cutover note:

• for standalone runtime deployment, use the docs in C:\dev\aindy-runtime
• for app-profile deployment, app manifests, client ownership, and Alembic operations, use the docs in C:\dev\aindy-apps-monolith
• use this combined repo's deployment docs only as monolith-era reference or migration context

This repository still contains historical product framing and compatibility surfaces from earlier A.I.N.D.Y. and Masterplan Infinite Weave iterations.

Treat that material as legacy context unless it is clearly referenced from the current docs index. The primary current system lives in:

• AINDY/
• apps/
• client/
• docs/