Skip to content

README.md

Latest commit

 

History

History
310 lines (230 loc) · 11.3 KB

README.md

File metadata and controls

310 lines (230 loc) · 11.3 KB
Raw

🧬 Autonomous Organism

Self-evolving digital organism — Sense · Think · Act · Evolve.

An experimental autonomous SaaS engine that continuously scans the web for human problems, scores and picks the best opportunity, generates an MVP, drafts marketing campaigns, and feeds every result back into a long-term memory store.

Built with Vite + React 18 + TypeScript + Tailwind on the frontend and Supabase (Postgres + Auth + Edge Functions in Deno) on the backend.

📑 Table of Contents

  1. Architecture
  2. Quick Start
  3. Environment Variables
  4. Database Setup
  5. Edge Functions
  6. Development
  7. Testing
  8. Deployment
  9. Security
  10. License

🏗 Architecture

┌──────────────────────────────────────────────────────────┐
│                  AUTONOMOUS ORGANISM                       │
├──────────────────────────────────────────────────────────┤
│                                                            │
│   ┌─────────┐   ┌──────────┐   ┌─────────┐               │
│   │ SENSE   │──▶│ DECISION │──▶│ FACTORY │               │
│   │ (RSS+HN)│   │ (score)  │   │ (Next.js)│              │
│   └─────────┘   └──────────┘   └────┬────┘               │
│        │                              │                    │
│        ▼                              ▼                    │
│   ┌─────────┐   ┌──────────┐   ┌─────────┐               │
│   │ MEMORY  │◀──│ GROWTH   │◀──│ IMMUNE  │               │
│   │ (logs)  │   │ (mktg)   │   │ (limits)│               │
│   └─────────┘   └──────────┘   └─────────┘               │
│        │                                                   │
│        ▼                                                   │
│   ┌──────────┐                                            │
│   │SCHEDULER │  hourly / daily / weekly / monthly         │
│   │ (cycle)  │                                            │
│   └──────────┘                                            │
│                                                            │
└──────────────────────────────────────────────────────────┘
Layer Stack
Frontend Vite, React 18, TypeScript, Tailwind, shadcn/ui, Radix UI, TanStack Query
Backend Supabase Postgres (with Row Level Security), Supabase Auth, Supabase Edge Functions (Deno)
AI (optional) Any OpenAI-compatible endpoint (OPENAI_BASE_URL) — OpenAI, OpenRouter, Ollama, Azure OpenAI
Container Docker + docker-compose
CI GitHub Actions

The standalone Node modules at the repo root (sense/, decision/, factory/, memory/, immune/, scheduler/) are the original prototype implementation. They are kept for reference; the live system uses the Supabase Edge Functions under supabase/functions/.

🚀 Quick Start

# 1. Clone the repository
git clone https://github.com/dhaher-labs/Autonomous-Organism.git
cd Autonomous-Organism

# 2. Install dependencies (Node 20+)
npm ci

# 3. Configure environment
cp .env.example .env
#   ↳ fill in VITE_SUPABASE_URL and VITE_SUPABASE_PUBLISHABLE_KEY

# 4. Apply the database migration
#   ↳ run supabase/migrations/*.sql in your Supabase SQL editor

# 5. Deploy the Edge Functions
supabase functions deploy bootstrap
supabase functions deploy ingest-sense
supabase functions deploy run-decision
supabase functions deploy run-factory
supabase functions deploy run-growth
supabase functions deploy update-scheduler
supabase functions deploy health

# 6. Set backend secrets (Project Settings → Edge Functions → Secrets)
#   ↳ see Environment Variables below

# 7. Start the dev server
npm run dev
#   ↳ open http://localhost:8080

The app renders a configuration notice instead of a blank screen when Supabase env vars are missing, so you can verify the build before connecting a backend.

🔐 Environment Variables

Frontend (.env)

Only VITE_* variables are exposed to the browser. Never put secrets here.

Variable Required Description
VITE_SUPABASE_URL ✅ Supabase project URL, e.g. https://abcd.supabase.co
VITE_SUPABASE_PUBLISHABLE_KEY ✅ Supabase anon/publishable key (browser-safe)
VITE_AI_MODEL ❌ Override default AI model (gpt-4o-mini)
VITE_SENTRY_DSN ❌ Sentry DSN for client-side error reporting

Backend (Supabase Edge Function secrets)

Set via supabase secrets set .... Never ship these to the browser.

Secret Required Description
SUPABASE_URL ✅ Same Supabase project URL
SUPABASE_SERVICE_ROLE_KEY ✅ Service-role key (full DB access)
SUPABASE_PUBLISHABLE_KEY ✅ Anon key (used to validate the caller's JWT)
SUPABASE_FUNCTION_ALLOW_ORIGIN ✅ (prod) Allowed CORS origin. Use your exact frontend URL.
OPENAI_API_KEY ❌ If unset, engines fall back to heuristic mode
OPENAI_BASE_URL ❌ Any OpenAI-compatible endpoint
AI_MODEL ❌ Model name, default gpt-4o-mini

🗄 Database Setup

The complete schema lives in supabase/migrations/20260123131529_9a3cd4f4-18df-42fe-8b52-a1c716fd4b8a.sql.

It creates:

  • organizations — tenant root
  • profiles — maps auth users to org + role (owner / user)
  • problem_sources — RSS / HackerNews feeds to scan
  • problem_raw / problem_clean — ingested complaints (with dedup hash)
  • idea_candidates — scored themes from the Decision engine
  • engine_runs — one row per engine invocation (sense/decision/factory/growth/memory)
  • engine_logs — fine-grained run logs
  • scheduler_config — guardrails + kill switch (per org)

Row Level Security is enabled on every table. The migration defines current_org_id(), is_org_member(), and is_org_owner() helper functions; every policy uses them so a user can only ever read or write rows belonging to their own organization.

Apply via:

supabase db push
# or paste the SQL into the Supabase dashboard SQL editor

⚙️ Edge Functions

All functions live under supabase/functions/ and share _shared/mod.ts for CORS, auth, validation, and the engine-run lifecycle.

Function Method Description
bootstrap POST Idempotently creates org + profile + scheduler config + default sources for the caller
ingest-sense POST Pulls enabled RSS / HN sources, dedupes via content hash, stores problem_raw + problem_clean
run-decision POST Scores problems (sentiment + automation + money), optionally uses AI, persists top idea_candidates
run-factory POST Generates a Next.js project template for the top idea (AI-enhanced when configured)
run-growth POST Drafts marketing campaigns + computes deterministic simulated metrics
update-scheduler POST Updates scheduler_config (kill switch, guardrails). Validates input ranges.
health GET Liveness + readiness probe — returns 200 when secrets + DB round-trip both succeed

Every mutating function:

  1. Resolves the caller's org via resolveOrg() (validates JWT)
  2. Loads scheduler_config via loadGuardrails()
  3. Calls assertNotKilled() — throws 423 Locked if kill switch is on
  4. Wraps its work in withEngineRun() so a run row + logs are always created, even on failure

💻 Development

npm run dev          # start Vite dev server (port 8080)
npm run lint         # ESLint
npm run typecheck    # tsc -b (project references)
npm run test         # Vitest once
npm run test:watch   # Vitest in watch mode
npm run test:coverage
npm run build        # production build → dist/
npm run preview      # serve the built dist/ locally

Docker

docker compose up --build
# ↳ http://localhost:8080

The Dockerfile uses a two-stage build (builder → serve runtime) and runs as a non-root user with a HEALTHCHECK.

🧪 Testing

Tests use Vitest + Testing Library and live under src/test/.

File What it covers
example.test.ts Smoke test
decision.test.ts Sentiment scoring shared by client + edge function
config-notice.test.tsx ConfigNotice renders correctly when Supabase is unconfigured

To add a test, drop a *.test.ts / *.test.tsx file anywhere under src/ — Vitest auto-discovers it.

🚢 Deployment

Frontend → Vercel / Netlify / any static host

npm run build
# deploy the dist/ directory

Make sure to set the VITE_* env vars in your hosting provider's build settings.

Backend → Supabase

supabase db push          # apply migrations
supabase functions deploy bootstrap ingest-sense run-decision \
  run-factory run-growth update-scheduler health
supabase secrets set --env-file .env.production

Health checks

Point your uptime monitor (UptimeRobot, BetterStack, etc.) at the deployed health Edge Function URL. It returns 200 OK only when secrets are configured and the DB round-trips.

🛡 Security

  • Row Level Security is enabled on every Postgres table.
  • Edge functions validate the caller's JWT via supabase.auth.getUser().
  • The service-role key is never shipped to the browser.
  • update-scheduler validates every input range server-side.
  • CORS origin is configurable via SUPABASE_FUNCTION_ALLOW_ORIGIN. Set it to your exact frontend URL in production.
  • The kill switch (scheduler_config.kill_switch) halts all engine runs immediately. It's surfaced as a destructive action in the UI header.

Reporting a Vulnerability

Please do not open a public issue. Email mulkymalikuldhr@agentmail.to with reproduction steps and affected versions. We acknowledge within 48 hours and ship a fix within 7 days for critical issues.

📦 Part of Dhaher Labs

This project is part of the Dhaher Labs ecosystem — 35+ open-source projects focused on practical AI systems, quantitative research, cybersecurity tools, and IoT platforms.

📄 License

See LICENSE.

"Pemilik bukan bikin produk. Pemilik menciptakan spesies digital."