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.
313 lines (239 loc) • 8.13 kB
Markdown
title: Architecture Summary
dimension: things
category: plans
tags: ai, 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/architecture-summary.md
Purpose: Documents one platform deployment architecture - quick reference
For AI agents: Read this to understand architecture summary.
# ONE Platform Deployment Architecture - Quick Reference
## ✅ CORRECT Architecture
```
/web (development - single source of truth)
├─→ git push → one-ie/web (website source repo)
├─→ sync to apps/oneie/ → git push → one-ie/oneie → one.ie
└─→ sync to apps/one/ → git push → one-ie/one → demo.one.ie
↓
npx oneie clones
```
## Projects & Repositories
| Purpose | Project Name | GitHub Repo | Cloudflare Project | Domain |
| ------------------ | ------------ | ------------ | ------------------ | ------------- |
| **Website Source** | web | one-ie/web | N/A | (source only) |
| **Main Website** | oneie | one-ie/oneie | oneie | one.ie |
| **Demo/Starter** | one | one-ie/one | one | demo.one.ie |
## Key Mappings
### Website Source (one-ie/web)
- **Source:** Local `/web` (development - single source of truth)
- **Repo:** `one-ie/web` (website code only, git repo)
- **Purpose:** Website source repository
- **Usage:** Pushed from local `/web` development
### Main Website (one.ie)
- **Source:** Local `/web`, `/one`, `/.claude` synced to `apps/oneie/`
- **Repo:** `one-ie/oneie` (full structure: web/, one/, .claude/)
- **Cloudflare:** `oneie` project
- **Domain:** https://one.ie
- **Purpose:** Full platform + marketing
- **Features:** Backend ON, Admin OFF, Full navigation
### Demo/Starter (demo.one.ie)
- **Source:** Local `/web`, `/one`, `/.claude` synced to `apps/one/`
- **Repo:** `one-ie/one` (full structure: web/, one/, .claude/)
- **Cloudflare:** `one` project
- **Domain:** https://demo.one.ie
- **Also:** `npx oneie` clones `one-ie/web` for website
- **Purpose:** Starter template for developers
- **Features:** Backend OFF, No admin, Minimal navigation
## Release Commands
```bash
# Push website source
cd web && git push origin main
# → Updates one-ie/web (single source of truth)
# Deploy main website
./scripts/release.sh patch main
# → Syncs /web, /one, /.claude to apps/oneie/
# → Pushes apps/oneie/ to one-ie/oneie
# → Deploys to one.ie
# Deploy demo/starter
./scripts/release.sh patch demo
# → Syncs /web, /one, /.claude to apps/one/
# → Pushes apps/one/ to one-ie/one
# → Deploys to demo.one.ie
# Deploy all
cd web && git push && cd .. && ./scripts/release.sh patch main && ./scripts/release.sh patch demo
```
## Environment Files
```bash
# web/.env.local (development - full features)
ORG_NAME=one
ORG_WEBSITE=https://one.ie
ONE_BACKEND=on
ENABLE_ADMIN_FEATURES=true
SITE_TYPE=development
# web/.env.main (for one.ie)
ORG_NAME=one
ORG_WEBSITE=https://one.ie
ONE_BACKEND=on
ENABLE_ADMIN_FEATURES=false
SITE_TYPE=main
# web/.env.demo (for demo.one.ie)
ORG_NAME=one
ORG_WEBSITE=https://demo.one.ie
ONE_BACKEND=off
ENABLE_ADMIN_FEATURES=false
SITE_TYPE=demo
```
## Directory Structure
```
ONE/ # Local workspace
├── web/ # Development website (all features)
├── one/ # Documentation
├── .claude/ # Claude configuration
│
└── apps/
├── oneie/ # Main site assembly
│ ├── web/ # → one.ie
│ ├── one/ # Documentation copy
│ └── .claude/ # Claude config copy
│
└── one/ # Demo site assembly
├── web/ # → demo.one.ie
├── one/ # Documentation copy
└── .claude/ # Claude config copy
GitHub Repositories (synced from apps/):
one-ie/oneie/ # Main site repo
├── web/ # Main website code
├── one/ # Documentation
└── .claude/ # Claude config
one-ie/one/ # Demo/starter repo
├── web/ # Demo website code
├── one/ # Documentation
└── .claude/ # Claude config
```
## User Flows
### Flow 1: Visit Main Website
```
User → one.ie
→ Full platform experience
→ Backend enabled
→ Can sign up/sign in
→ Access all features
```
### Flow 2: Try Demo Online
```
User → demo.one.ie
→ Starter template preview
→ Backend disabled (frontend-only)
→ See what they'll download
→ No signup required
```
### Flow 3: Download Starter
```
Developer → npx oneie
→ Clones entire one-ie/one repo
→ Gets:
• web/ (same as demo.one.ie)
• one/ (full documentation)
• .claude/ (Claude config)
→ Complete starter kit
→ Can customize locally
→ Can connect own backend
```
## Cloudflare Projects to Create
1. **Project: oneie**
- Custom domain: one.ie
- Build command: `cd web && bun run build`
- Build output: `web/dist`
- Root directory: `/` (repo has web/, one/, .claude/)
- Environment: Production (main site)
2. **Project: one**
- Custom domain: demo.one.ie
- Build command: `cd web && bun run build`
- Build output: `web/dist`
- Root directory: `/` (repo has web/, one/, .claude/)
- Environment: Demo (starter)
## GitHub Repositories
1. **one-ie/web** (EXISTING)
- Website source code only
- Pushed from: `/web` (local development)
- Cloned by: `npx oneie` (for website)
- Purpose: Single source of truth for website
2. **one-ie/oneie** (NEW - create this)
- Full structure: `web/`, `one/`, `.claude/`
- Synced from: `apps/oneie/`
- Deploys: `web/` to one.ie
- Purpose: Main website assembly
3. **one-ie/one** (EXISTING)
- Full structure: `web/`, `one/`, `.claude/`
- Synced from: `apps/one/`
- Deploys: `web/` to demo.one.ie
- Purpose: Demo/starter assembly
4. **one-ie/cli** (EXISTING)
- CLI package on npm
- Clones `one-ie/web` for website
- Bundles `one/` and `.claude/` docs
## Quick Checklist
**Setup:**
- [ ] Create `one-ie/oneie` repo on GitHub
- [ ] Create Cloudflare project `oneie` → one.ie
- [ ] Create Cloudflare project `one` → demo.one.ie
- [ ] Create environment files (`.env.main`, `.env.demo`)
- [ ] Create feature flags config (`src/config/features.ts`)
**Test:**
- [ ] Build main site locally: `cp .env.main .env.local && bun run build`
- [ ] Build demo locally: `cp .env.demo .env.local && bun run build`
- [ ] Verify feature flags work correctly
**Deploy:**
- [ ] Deploy main: `./scripts/release.sh patch main`
- [ ] Deploy demo: `./scripts/release.sh patch demo`
- [ ] Verify one.ie works (full platform)
- [ ] Verify demo.one.ie works (starter)
- [ ] Test `npx oneie` downloads correct version
## Common Mistakes to Avoid
❌ **DON'T:**
- Deploy development environment to production
- Mix main site and demo features
- Forget to sync demo to one-ie/one repo
- Use wrong Cloudflare project for deployment
✅ **DO:**
- Keep `/web` as single source of truth
- Use environment files to control features
- Test both builds before deploying
- Sync demo to one-ie/one for npx distribution
## Summary
**One Codebase, Two Outputs:**
1. **one.ie** (oneie project)
- Full platform
- Marketing site
- Backend enabled
- For: Public visitors
2. **demo.one.ie + npx oneie** (one project)
- Starter template
- Minimal features
- Backend disabled
- For: Developers
**Single command to deploy both:**
```bash
./scripts/release.sh patch main && ./scripts/release.sh patch demo
```
**For complete documentation, see:**
- `separate-demo.md` - Full implementation guide
- `deployment-architecture.md` - Visual architecture overview