Project Structure
Relevant source files
The following files were used as context for generating this wiki page:
The lucky project is a monorepo designed to support the development of self-improving agentic workflows. It uses a modular architecture, separating concerns into distinct packages for the core engine, tools, data models, and persistence, while applications like the web UI and examples consume these packages. This structure facilitates independent development, testing, and versioning of each component.
The project leverages Turborepo for managing the monorepo, which optimizes build and test processes by understanding the dependencies between packages. The entire codebase is written in TypeScript, with a strong emphasis on type safety enforced through Zod contracts, especially in the foundational @lucky/shared package.
Monorepo Layout
The repository is organized into three primary top-level directories: apps, packages, and tests. This separation isolates deployable applications from reusable library code and testing infrastructure.
Sources: README.md:27-39, tests/README.md:5-13
This diagram shows the high-level directory structure of the monorepo.
Key Directories
| Directory | Purpose |
|---|---|
apps/ | Contains deployable applications, such as the Next.js web interface and example workflow definitions. |
packages/ | Houses reusable code libraries (packages) that form the core functionality of the system. |
tests/ | Contains integration and end-to-end (E2E) tests that span across multiple packages and services. |
Sources: README.md:27-39, tests/README.md:5-13
Package Dependencies and Build Order
The monorepo is structured with a clear dependency hierarchy, ensuring that foundational packages are built before those that depend on them. The build order is managed by Turborepo and is critical for maintaining a stable development environment.
Sources: README.md:41, packages/shared/README.md:124-126
The build pipeline is defined as follows:
shared → models → tools → core → web
This diagram illustrates the dependency flow between the core packages, dictating the build order.
Core Packages
| Package | Description | Source |
|---|---|---|
@lucky/shared | The foundational package containing Zod contracts, TypeScript types, and shared utilities. It is the single source of truth for data structures. | packages/shared/README.md:3-6 |
@lucky/models | A multi-provider model registry for services like OpenAI, Anthropic, etc. | README.md:33 |
@lucky/tools | A unified framework for both internal TypeScript Code Tools and external MCP Tools. | README.md:34, packages/tools/README.md:3-9 |
@lucky/core | The main workflow execution engine. It manages the Directed Acyclic Graph (DAG), agent nodes, evolution, and memory systems. | README.md:35, packages/core/README.md:3-6 |
@lucky/adapter-supabase | An optional persistence layer that implements the core persistence interface using Supabase for data storage. | README.md:36, packages/adapter-supabase/REFACTORING.md:3-5 |
@lucky/mcp-server | A Model Context Protocol (MCP) server implementation for web scraping capabilities. | packages/mcp-server/README.md:10 |
Applications
The apps directory contains the user-facing and example implementations built upon the core packages.
Sources: README.md:28-31
apps/web
This is the main user interface, built with Next.js. It provides tools for creating, visualizing, and managing agentic workflows, as well as configuring settings and connectors. It depends on most of the core packages to function.
Sources: README.md:29, apps/web/package.json
apps/examples
This application serves as a collection of example tool definitions and workflow configurations. It is used for demonstrating capabilities and for providing runnable examples for developers.
Sources: README.md:30
Tool Architecture
The system supports two types of tools, managed by the @lucky/tools package. This hybrid approach allows for both tightly integrated, type-safe functions and language-agnostic external processes.
Sources: README.md:100-115, packages/tools/README.md:11-15
- Code Tools: TypeScript functions located in
packages/tools/src/definitions/. They are explicitly registered and offer full type safety. Examples includecsvReaderandhumanApproval. - MCP Tools: External servers that conform to the Model Context Protocol (MCP). They are configured via a
mcp-secret.jsonfile and allow integration with tools written in any language, such astavilyandfirecrawl.
Tool Registration Flow
Adding a new tool name is a structured process that ensures type safety across the monorepo.
This diagram shows the developer workflow for registering a new tool, ensuring type safety from definition to usage.
Persistence Layer
The project features a pluggable persistence architecture, allowing developers to switch between a cloud-based backend and a local, in-memory mock. This is managed by a factory pattern.
Sources: packages/adapter-supabase/REFACTORING.md:10-17, README.md:164-167
Persistence Factory
The createPersistence factory in @together/adapter-supabase allows swapping implementations. This is particularly useful for testing, as it avoids the need for a live database connection. The USE_MOCK_PERSISTENCE=true environment variable can be used to run the system without Supabase.
Sources: packages/adapter-supabase/REFACTORING.md:10-17, README.md:164-165
This diagram illustrates the Dependency Inversion Principle applied to the persistence layer, where the core engine depends on an interface, not a concrete implementation.
Testing Structure
The tests directory is dedicated to integration and end-to-end tests, keeping them separate from unit tests that are co-located with source code in the packages directory.
Sources: tests/README.md:3-13
Test Types
| Directory | Test Type | When to Run | Purpose |
|---|---|---|---|
e2e-essential/smoke/ | Smoke Tests | On every commit (pre-commit hook) | Validates critical paths and essential functionality quickly. |
e2e-essential/gate/ | Gate Tests | Before every push (pre-push hook) | Provides comprehensive validation before code is pushed to the remote repository. |
integration/ | Integration Tests | Manually or in CI | Tests how multiple modules work together, including external dependencies like APIs and databases. |
Sources: tests/README.md:27-48, README.md:65-72
Conclusion
The lucky project is organized as a well-structured monorepo that emphasizes modularity, type safety, and a clear separation of concerns. The use of Turborepo for build orchestration, Zod for data contracts, and a pluggable persistence layer creates a robust and developer-friendly environment. The distinct apps, packages, and tests directories, combined with a clear package dependency hierarchy, allow for scalable development and maintenance of the complex agentic workflow system.