oneie
Version:
Build apps, websites, and AI agents in English. Zero-interaction setup for AI agents (Claude Code, Cursor, Windsurf). Download to your computer, run in the cloud, deploy to the edge. Open source and free forever.
470 lines (361 loc) • 16.3 kB
Markdown
title: Deployment Architecture
dimension: things
category: plans
tags: architecture, system-design
scope: global
created: 2025-11-03
updated: 2025-11-03
version: 1.0.0
ai_context: |
This document is part of the things dimension in the plans category.
Location: one/things/plans/deployment-architecture.md
Purpose: Documents one platform deployment architecture
For AI agents: Read this to understand deployment architecture.
# ONE Platform Deployment Architecture
## Current vs. New Architecture
### Current Architecture (Single Deployment)
```
┌─────────────────────────────────────────────────────────────┐
│ /web (development) │
│ - Full features │
│ - localhost:4321 │
└──────────────────┬──────────────────────────────────────────┘
│
↓ rsync
┌─────────────────────────────────────────────────────────────┐
│ apps/one/web │
│ - Assembly for deployment │
└──────────────────┬──────────────────────────────────────────┘
│
↓ wrangler deploy
┌─────────────────────────────────────────────────────────────┐
│ Cloudflare Pages: web.one.ie │
│ - Single deployment │
│ - Everything goes here │
└─────────────────────────────────────────────────────────────┘
```
**Problem:** Development code deployed directly to production
### New Architecture (Multi-Target Deployment)
```
┌──────────────────────────────────────────────────────────────┐
│ /web (DEVELOPMENT) │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ - Single source of truth │
│ - Full ONE Platform features │
│ - All admin tools and experimental features │
│ - Development environment (.env.local) │
│ - Test: bun run dev (localhost:4321) │
└────────────────────┬─────────────────────────────────────────┘
│
┌───────────┴───────────┐
↓ ↓
┌─────────────────────┐ ┌──────────────────────┐
│ TARGET 1: MAIN │ │ TARGET 2: DEMO │
│ ━━━━━━━━━━━━━━━━━ │ │ ━━━━━━━━━━━━━━━━━━ │
│ apps/oneie/web │ │ apps/one/web │
│ (.env.main) │ │ (.env.demo) │
│ │ │ │
│ Features: │ │ Features: │
│ ✅ Full platform │ │ ⬜ Starter template │
│ ✅ Marketing │ │ ⬜ Minimal UI │
│ ✅ Backend ON │ │ ⬜ Backend OFF │
│ ⬜ Admin tools OFF │ │ ⬜ No admin │
└─────────┬───────────┘ └──────────┬───────────┘
│ │
↓ ↓
┌───────────────────┐ ┌────────────────────────────────┐
│ Cloudflare: oneie│ │ Cloudflare: one │
│ ━━━━━━━━━━━━━━━ │ │ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ one.ie │ │ demo.one.ie │
│ (main website) │ │ (live demo) │
└───────────────────┘ └─────────────┬──────────────────┘
│
↓ git push
┌──────────────────────────────────┐
│ GitHub: one-ie/one │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ Starter template repo │
└─────────────┬────────────────────┘
│
↓
┌──────────────────────────────────┐
│ npm: oneie package │
│ ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ │
│ npx oneie │
│ Downloads from one-ie/one │
└──────────────────────────────────┘
```
## The Three Outputs
### 1. Main Website (one.ie)
**Purpose:** Full platform + marketing
**Source:** `/web`, `/one`, `/.claude` → `apps/oneie/` → `one-ie/oneie` → Cloudflare `oneie`
**Environment:** `.env.main`
```bash
ORG_NAME=one
ORG_WEBSITE=https://one.ie
ONE_BACKEND=on
ENABLE_ADMIN_FEATURES=false
SHOW_FULL_NAVIGATION=true
SITE_TYPE=main
```
**Features:**
- ✅ Complete navigation
- ✅ All marketing pages
- ✅ Backend integration (Convex)
- ✅ Authentication
- ⬜ Admin panel (not exposed to public)
- ⬜ Experimental features
**Audience:** Public visitors, potential customers
### 2. Demo Website (demo.one.ie)
**Purpose:** Live starter template
**Source:** `/web`, `/one`, `/.claude` → `apps/one/` → `one-ie/one` → Cloudflare `one`
**Environment:** `.env.demo`
```bash
ORG_NAME=one
ORG_WEBSITE=https://demo.one.ie
ONE_BACKEND=off
ENABLE_ADMIN_FEATURES=false
SHOW_FULL_NAVIGATION=false
SITE_TYPE=demo
```
**Features:**
- ✅ Minimal navigation (Blog + License only)
- ✅ GetStartedPrompt component
- ⬜ Backend disabled (frontend-only)
- ⬜ No authentication required
- ⬜ Clean starter experience
**Audience:**
- Developers visiting to see the demo
- Users who want to try before downloading
- Matches exactly what they'll get from `npx oneie`
### 3. Downloadable (npx oneie)
**Purpose:** Local development starter
**Source:** `one-ie/one` repository
**Distribution:**
1. **Via npm:** `npx oneie` clones entire `one-ie/one` repo
2. **Via git:** `git clone one-ie/one`
**What users get:**
- `web/` - Complete website code (same as demo.one.ie)
- `one/` - Full documentation
- `.claude/` - Claude configuration
- Complete starter kit with all resources
**Same as:** demo.one.ie (plus docs and Claude config)
**Audience:** Developers starting new projects
## Release Workflow
### Development Workflow
```bash
# 1. Develop with full features
cd /web
bun run dev
# → localhost:4321 with full ONE Platform
# 2. Make changes
# Edit components, add features, etc.
# 3. Test locally with different configs
cp .env.main .env.local
bun run build && bun run preview
# → Test main site experience
cp .env.demo .env.local
bun run build && bun run preview
# → Test demo/starter experience
# 4. Commit changes
git add .
git commit -m "feat: new feature"
git push
```
### Release Workflow
```bash
# From workspace root
# Option A: Release main site only
./scripts/release.sh patch main
# → Syncs /web, /one, /.claude to apps/oneie/
# → Pushes apps/oneie/ to one-ie/oneie
# → Builds apps/oneie/web with .env.main
# → Deploys to one.ie
# Option B: Release demo site only
./scripts/release.sh patch demo
# → Syncs /web, /one, /.claude to apps/one/
# → Pushes apps/one/ to one-ie/one
# → Builds apps/one/web with .env.demo
# → Deploys to demo.one.ie
# → Users can clone via npx oneie
# Option C: Release both (recommended)
./scripts/release.sh patch main && ./scripts/release.sh patch demo
# → Updates both deployments
# → Main: one-ie/oneie → one.ie
# → Demo: one-ie/one → demo.one.ie + npx oneie
```
## Directory Structure
```
ONE/ # Local workspace
│
├── web/ # Development website (single source of truth)
│ ├── .env.local # Development config (full features)
│ ├── .env.main # Main site config (for one.ie)
│ ├── .env.demo # Demo config (for demo.one.ie)
│ ├── src/
│ │ ├── config/
│ │ │ └── features.ts # Feature flags
│ │ ├── components/
│ │ ├── pages/
│ │ └── ...
│ └── package.json
│
├── one/ # Documentation (single source of truth)
│ ├── things/
│ ├── connections/
│ ├── events/
│ ├── knowledge/
│ └── ...
│
├── .claude/ # Claude config (single source of truth)
│ ├── agents/
│ ├── commands/
│ └── hooks/
│
├── apps/ # Assembly targets
│ ├── oneie/ # Main site (full structure)
│ │ ├── web/ # Synced from /web
│ │ ├── one/ # Synced from /one
│ │ ├── .claude/ # Synced from /.claude
│ │ └── package.json
│ │ → Pushed to one-ie/oneie → Deployed to one.ie
│ │
│ └── one/ # Demo site (full structure)
│ ├── web/ # Synced from /web
│ ├── one/ # Synced from /one
│ ├── .claude/ # Synced from /.claude
│ └── package.json
│ → Pushed to one-ie/one → Deployed to demo.one.ie
│
├── cli/ # npm package
│ └── index.js # Downloads entire one-ie/one repo
│
└── scripts/
└── release.sh # Multi-target release script
GitHub Repositories (full structure):
one-ie/oneie/ # Main site repo
├── web/ # Website code
├── one/ # Documentation
└── .claude/ # Claude config
one-ie/one/ # Demo/starter repo (what npx oneie clones)
├── web/ # Website code
├── one/ # Documentation
└── .claude/ # Claude config
```
## Key Benefits
### ✅ Single Codebase
- Develop in one place (`/web`)
- No duplicate code to maintain
- Changes propagate to both sites
### ✅ Environment-Based
- Simple `.env` files control features
- No complex build configuration
- Easy to test both versions locally
### ✅ Clean Separation
- Main site has full features
- Demo site is minimal starter
- No development artifacts in production
### ✅ Consistent User Experience
- `npx oneie` downloads exact same code as web.one.ie
- Users can try online before downloading
- No surprises when they clone locally
### ✅ Independent Deployments
- Deploy main site without affecting demo
- Update demo without touching main site
- Test in production safely
### ✅ Version Control
- Each site tracks its own history
- `one-ie/one` for main site
- `one-ie/oneie` for demo/starter
- Clean git history per deployment
## Comparison to Current Setup
| Aspect | Before | After |
| ------------------- | ------------------ | --------------------------------- |
| **Development** | `/web` | `/web` (unchanged) |
| **Main Site** | ❌ N/A | ✅ `one.ie` (full platform) |
| **Demo Site** | ❌ N/A or mixed | ✅ `demo.one.ie` (starter only) |
| **Downloadable** | ❌ Mixed with main | ✅ `one-ie/one` (clean starter) |
| **Deployments** | 1 (everything) | 2 (main + demo) |
| **Repositories** | 1 (`one-ie/one`) | 2 (`one-ie/one` + `one-ie/oneie`) |
| **Cloudflare** | 1 project | 2 projects (`oneie` + `one`) |
| **Feature Control** | ❌ No separation | ✅ Environment flags |
| **CLI Downloads** | Mixed content | Clean starter template |
## Implementation Checklist
### Phase 1: Setup (Week 1)
- [ ] Create `web/.env.main` with main site config
- [ ] Create `web/.env.demo` with demo config
- [ ] Create `web/src/config/features.ts` with feature flags
- [ ] Test both builds locally
### Phase 2: Infrastructure (Week 2)
- [ ] Create GitHub repository: `one-ie/oneie` (main site)
- [ ] `one-ie/one` already exists (demo/starter)
- [ ] Create Cloudflare project: `oneie` (for one.ie)
- [ ] Create Cloudflare project: `one` (for demo.one.ie)
- [ ] Configure custom domains
### Phase 3: Release Script (Week 3)
- [ ] Update `scripts/release.sh` with multi-target support
- [ ] Add logic to sync to `apps/oneie/`
- [ ] Add logic to push to `one-ie/oneie`
- [ ] Test sync without deployment
### Phase 4: Components (Week 3)
- [ ] Update components to use feature flags
- [ ] Gate admin features
- [ ] Simplify navigation for demo
- [ ] Test both versions
### Phase 5: Deploy (Week 4)
- [ ] Deploy main site: `./scripts/release.sh patch main`
- [ ] Verify one.ie works correctly
- [ ] Deploy demo site: `./scripts/release.sh patch demo`
- [ ] Verify demo.one.ie works correctly
- [ ] Verify `one-ie/one` repo updated
### Phase 6: CLI (Week 4)
- [ ] Update CLI to download from `one-ie/one`
- [ ] Test `npx oneie` downloads correct version
- [ ] Verify downloaded code matches demo.one.ie
## Quick Reference
**Develop:**
```bash
cd web && bun run dev
```
**Test main site build:**
```bash
cp web/.env.main web/.env.local && cd web && bun run build
```
**Test demo build:**
```bash
cp web/.env.demo web/.env.local && cd web && bun run build
```
**Deploy main site:**
```bash
./scripts/release.sh patch main
```
**Deploy demo site:**
```bash
./scripts/release.sh patch demo
```
**Deploy both:**
```bash
./scripts/release.sh patch main && ./scripts/release.sh patch demo
```
**URLs:**
- Main: https://one.ie
- Demo: https://demo.one.ie
- CLI: npx oneie (downloads from one-ie/one)
**Repositories:**
- Main: https://github.com/one-ie/oneie (main website)
- Demo: https://github.com/one-ie/one (starter template)
- CLI: https://github.com/one-ie/cli (downloads from one-ie/one)
**Result:** Clean separation between development, main site, and demo/starter template with single codebase.