🌱 Lily

Never let a houseplant die from neglect again.

Lily gives every plant you own a personalized, species-aware care schedule — backed by AI diagnosis, a 10,000-species camera scanner, and smart reminders that know your plant, your room, and your local weather.

What is Lily

Lily is a cross-platform (iOS/Android) plant-care app for houseplant owners who keep killing their plants by forgetting to care for them. Each plant gets its own profile — photo, species, room, health — plus a personalized watering, fertilizing, and misting schedule that fires push notifications based on species, location, and local conditions. You identify plants with the camera (10,000+ species), log care actions, and chat with an AI that has full context on your specific plant for diagnosis like yellowing leaves or root rot.

This repository is the full TypeScript/Bun monorepo behind Lily: backend, mobile app, marketing site, admin dashboard, and supporting AI services.

Engineering highlights

If you're here to read code, these are the parts worth a look:

• Effect-first, end to end. The entire stack — backend, mobile app, web, admin — is built on Effect 3.x. Typed errors (Schema.TaggedError), dependency injection via layers, and Match.exhaustive over union types, with native JS escape hatches (Array.map, switch, ??, new Date()) deliberately avoided.
• Type-safe client/server contract. shared defines the domain with Effect Schema; both the API and its clients import the same schemas, so the wire contract is checked at compile time.
• RAG-grounded AI diagnosis. knowledge-db is a pgvector knowledge base (3,072-dim halfvec embeddings, HNSW + full-text hybrid search) that grounds per-plant AI answers in retrieved care knowledge.
• Native AR/ML scanning. plant-scanner is an iOS Expo native module using ARKit + TensorFlow Lite for on-device plant/pot detection, AR distance measurement, and ambient-light (lux) estimation.
• Agentic MCP server. mcp exposes Lily to AI assistants (ChatGPT) over the Model Context Protocol with OAuth 2.1 and rich HTML widgets.
• Monorepo discipline. Turborepo over Bun workspaces, Biome for format + lint, strict TypeScript project references, and CI gates (tsc + lint + test) enforced on every push.

Packages

Package	Description
api	Effect-based backend API server on Bun with Postgres, Redis, and schedulers
app	React Native (Expo) mobile app for plant care management
web	Next.js 16 static-export marketing site with i18n (en/fr) and an MDX blog
admin	Vite + React 19 internal admin dashboard for operating Lily
shared	Effect Schema domain types, typed errors, and service interfaces shared across packages
db	Primary PostgreSQL schema, migrations, and Drizzle client wired into Effect
knowledge-db	Pgvector RAG knowledge base: Drizzle schema plus Effect Postgres client layer
mcp	MCP server exposing Lily plant data and tools to AI clients
plant-scanner	iOS-only Expo native module for AR plant/pot scanning and measurement

Tech stack

Bun 1.4.3 · Node 24 LTS · TypeScript 7.0 (with @effect/tsgo) · Effect 4.0 · Turborepo ^2.11 · Biome 2.6 · Vitest 5 · Drizzle ORM ^0.45 · PostgreSQL 15 + pgvector (pg17) · Redis 7 · Expo ~58 / React Native 0.88 · React 19.3 · Next.js ^16 · Vite ^8

Quickstart

All commands run from the repository root — never cd into a package (Turbo + Bun workspaces handle per-package execution).

# 1. Start local infra: postgres, postgres-test, knowledge-db, knowledge-db-test, redis
docker compose up -d

# 2. Install all workspaces (also runs `prepare`: Husky hooks + `effect-tsgo patch`)
bun install

# 3. Provide env: copy the example and fill in the blanks
cp .env.example .env

# 4. Apply the Drizzle schema to local Postgres
#    (dev push — do NOT run `drizzle-kit generate`; migrations are hand-authored)
bun run --filter=@lily/db db:push

# 5. (RAG/knowledge features only) Apply the pgvector knowledge-base schema
bun run --filter=@lily/knowledge-db db:push

# 6. Start everything in watch mode via Turbo
#    (api serves at http://localhost:3000 with Swagger/OpenAPI)
bun run dev

Prerequisites: Bun 1.4.3 and Docker. The local Postgres/Redis defaults in .env.example match docker-compose.yml, so the core stack works out of the box.

Commands

Command	What it does
bun run dev	Watch mode across all packages that define dev (Turbo, persistent)
bun run build	Build all packages
bun run test	Run unit tests across all packages (Vitest in api/shared/mcp)
bun run test:integration	Run api integration tests against a real Postgres (loads .env.test.local)
bun run db:setup-test	Provision the test database (push to DATABASE_URL_TEST + setup script)
bun run lint	Biome lint/check across all packages
bun run lint:fix	Biome lint + autofix across all packages
bun run tsc	TypeScript typecheck (tsc --noEmit) — CI + pre-push gate
bun run tsc:build	Exercise the full TypeScript project-reference (composite) build graph
bun run clean	Remove build artifacts across all packages

Git hooks: pre-commit runs lint:fix on staged files; pre-push runs lint, tsc, then test.

Architecture

Lily is a TypeScript/Bun monorepo on Effect 3.x, orchestrated by Turborepo over Bun workspaces. The backend api is built on Effect Platform (HttpApi/HttpApiBuilder) serving REST endpoints with OpenAPI/Swagger on a Bun HTTP runtime (port 3000), layered as endpoints → handlers → services → repositories. The app (React Native/Expo) and admin dashboard are the two HTTP clients; both depend on shared for domain schemas, types, and typed errors so the client/server contract stays type-safe. db owns the primary PostgreSQL schema via Drizzle, which api reads and writes through the PgDrizzle repository layer.

For AI: knowledge-db is a separate pgvector PostgreSQL database (raw documents → processed chunks → ingest jobs) exposed via its own KnowledgeDrizzle tag; api's ai-chat service queries it with vector similarity search to ground per-plant diagnosis in retrieved care knowledge. plant-scanner is a native Expo module consumed by the app's add-plant flow (plant/pot detection, lux, AR distance, captured photos). mcp is a standalone Effect MCP server that calls api over HTTP to expose agentic tools (list-plants, get-care-tasks, ask-plant-question, …). web is the public Next.js marketing funnel, decoupled from the runtime backend.

app / plant-scanner ─┐
                     ├─▶ api ─┬─▶ db            (primary state)
admin ───────────────┘        ├─▶ knowledge-db  (pgvector RAG)
                              └─▶ push           (notifications)
mcp ─────────────────▶ api
web  (static marketing, no runtime backend)

Conventions

• Effect-first. Use Effect modules everywhere; native JS equivalents (arr.map, Object.keys, switch, ??, new Date(), …) are forbidden. See CODING_STANDARDS.md for the full mapping.
• Run from root. Never cd into a package — all scripts go through Turbo from the monorepo root.
• Drizzle, not Prisma. Database access is Drizzle ORM via @effect/sql-drizzle. Migrations are hand-authored SQL (packages/db/drizzle/); never run drizzle-kit generate (the journal is intentionally out of sync). Prod migrations run via db:migrate:prod.
• Typed errors. Errors are Schema.TaggedError propagated through the Effect system and handled by tag — never catchAll. Union types use Match.exhaustive.
• Monorepo discipline. Every package extends the root tsconfig.json, declares sideEffects, and pins the exact root typescript version. Use @ts-expect-error (with a rationale), never @ts-ignore.

Full coding rules live in CODING_STANDARDS.md; package rules in docs/agents/monorepo.md.

Contributing

Contributions are welcome! Start with CONTRIBUTING.md for the dev workflow, coding conventions, and PR process. Please also read our Code of Conduct.

• 🐛 Found a bug? Open an issue.
• 💡 Have an idea? Request a feature.
• 🔒 Found a vulnerability? Please report it privately — see SECURITY.md.

License

Lily is licensed under the GNU Affero General Public License v3.0. In short: you're free to use, study, modify, and share the code, but if you run a modified version as a network service you must make your source available under the same license.

Docs

• CODING_STANDARDS.md — authoritative Effect-first coding rules, plus pointers to each package's own rules.
• CLAUDE.md (also AGENTS.md) — entry point for coding agents: routes to the coding standards and the docs in docs/agents/.
• packages/api/README.md — backend request flow and the endpoints → handlers → services → repositories layering.
• packages/db/README.md — primary PostgreSQL schema map (users, plants, auth, chat, notifications, achievements).
• packages/shared/README.md — the domain model and cross-package contract: schemas, validation, and typed errors.
• docs/knowledge-pipeline-architecture.md — design of the pgvector knowledge-db RAG pipeline (ingest → chunk → embed → retrieve).
• docs/rag-implementation-plan.md — RAG implementation plan backing the api ai-chat grounding.
• docs/agents/domain.md — convention for the CONTEXT-MAP.md / per-package CONTEXT.md + docs/adr layout.