Getting Started & Local Setup
Relevant source files
The following files were used as context for generating this wiki page:
FusionOps (internally known as LP Factory) is an integrated control plane designed for building and deploying PPC and affiliate landing pages. The system utilizes an Astro 6 and React 19 frontend dashboard, supported by a backend composed of multiple Cloudflare Workers and a suite of D1 SQLite and Neon Postgres databases. Sources: README.md:1-5, CLAUDE.md:7-10
This guide outlines the technical requirements and procedural steps necessary to establish a local development environment and initialize the required cloud infrastructure. For more details on data management, refer to the Database Documentation. Sources: CLAUDE.md:14-30, INFRASTRUCTURE_SETUP.md:1-5
System Prerequisites
Before initializing the project, ensure your environment meets the following version requirements:
| Requirement | Version | Notes |
|---|---|---|
| Node.js | ≥ 22.0.0 | Bundled with npm. Verify via .nvmrc. |
| npm | Latest | Standard Node package manager. |
| Wrangler CLI | Latest | Required for Cloudflare Worker management. |
| Cloudflare Account | Active | Needed for D1, Pages, and Worker deployment. |
| Neon Account | Optional | Required for Postgres settings and site data. |
Sources: README.md:7-12, CLAUDE.md:31, scripts/setup-infrastructure.sh:12-16
Initial Repository Onboarding
The project uses a monorepo structure. Initial setup is handled via a bootstrap command that installs dependencies and performs environment sanity checks. Sources: README.md:14-18, CLAUDE.md:16-17
Setup Workflow
- Clone the Repository: Download the source code from GitHub.
- Bootstrap Dependencies: Run
npm run bootstrapto install all necessary packages and runsetup:check. - Environment Configuration: Copy
.env.exampleto.env. - Cloudflare Authentication: Execute
wrangler loginto authorize your local machine.
Sources: README.md:23-28, CLAUDE.md:16-20, scripts/setup-infrastructure.sh:18-20
This flow represents the standard onboarding process for a new developer.
Sources: README.md:14-40, scripts/setup-infrastructure.sh:220-230
Infrastructure Initialization
FusionOps requires multiple Cloudflare D1 databases and Worker services to function correctly. This can be automated using the provided setup scripts. Sources: INFRASTRUCTURE_SETUP.md:35-40, scripts/setup-infrastructure.js:15-28
Infrastructure Architecture
The following diagram illustrates the relationship between the local environment, Cloudflare Workers, and the database layers:
Architecture overview showing the connection between local development and cloud services.
Sources: INFRASTRUCTURE_SETUP.md:3-32, CLAUDE.md:280-290
Database Configuration
The system relies on three distinct D1 database instances. These must be created and linked to the corresponding workers via wrangler.toml files. Sources: INFRASTRUCTURE_SETUP.md:41-50, scripts/setup-infrastructure.js:31-40
| Database Name | Binding | Purpose |
|---|---|---|
fusionops-main | DB | Campaigns, templates, and site metadata. |
fusionops-pixel | DB | Click and conversion tracking events. |
fusionops-callback | DB | Lead notifications and webhook data. |
Sources: INFRASTRUCTURE_SETUP.md:41-50, scripts/setup-infrastructure.js:31-40
Using Automated Setup Scripts
Developers can use either the Bash or Node.js setup scripts located in the /scripts directory to automate the creation of databases and execution of migrations. Sources: scripts/setup-infrastructure.sh:1-10, scripts/setup-infrastructure.js:1-12
# To setup all infrastructure (D1, Migrations, and Workers)
node scripts/setup-infrastructure.js
# Or use the bash alternative
bash scripts/setup-infrastructure.sh
Sources: scripts/setup-infrastructure.js:10-12, scripts/setup-infrastructure.sh:260-270
Local Development Server
The main UI dashboard runs on Astro. To ensure consistency with Playwright E2E tests, the server is configured to use a fixed port. Sources: README.md:37-40, CLAUDE.md:22-24
UI Development
npm run dev
# Dashboard available at http://localhost:4321
The dev server automatically proxies requests starting with /api/* to the VITE_API_BASE URL defined in your .env file. Sources: README.md:37-45, CLAUDE.md:290-295
API Worker Development (Optional)
If modifying the backend API Workers, they can be run locally using Wrangler's development server. Sources: README.md:47-50, CLAUDE.md:52-53
cd apps/api-worker
npx wrangler dev
# API available at http://localhost:8787/api
After starting the local worker, update VITE_API_BASE in .env to point to the local instance. Sources: README.md:52-55, CLAUDE.md:290-300
Deployment Operations
Full system deployment involves building the Astro frontend and deploying multiple worker packages. Sources: scripts/deploy-all.js:1-12, CLAUDE.md:128-140
Deployment Components
The scripts/deploy-all.js script handles the following:
- Pre-flight Checks: Verifies Cloudflare authentication and tool versions.
- Build Web App: Executes
npm run buildin theapps/landerdirectory. - Deploy Workers: Iterates through
api-worker,cf-proxy,pixel-worker, andworkerto deploy via Wrangler. - Deploy Pages: Uploads the built static assets to Cloudflare Pages.
Sources: scripts/deploy-all.js:15-28, scripts/deploy-all.js:107-160
Deployment Commands
| Command | Action |
|---|---|
npm run deploy:org | Full organization deployment helper. |
node scripts/deploy-all.js --workers-only | Deploys only backend workers. |
node scripts/deploy-all.js --web-only | Deploys only the Astro dashboard. |
Sources: README.md:65, scripts/deploy-all.js:10-15
Conclusion
By following these setup procedures, developers establish a standardized environment that aligns with the FusionOps production architecture. The combination of Astro, Cloudflare Workers, and D1 provides a low-latency, scalable platform for landing page management. Verification of the setup can be performed by running the built-in test suites (npm test) or by checking the status via wrangler deployments list. Sources: README.md:60-65, INFRASTRUCTURE_SETUP.md:144-155