indie/PLAN.md

Indie — Independent Website Platform

A platform that lets anyone create, own, and publish their own static website without social media gatekeeping. Built with a drag-and-drop builder and LLM prompt-to-site generation. Every site is backed by a git repository. Users self-host or use free subdomain hosting.

---

Tech Stack

Layer	Technology
Backend	Java 17, Spring Boot 3.x, Gradle (Groovy)
Frontend	Angular 17, Angular Material, Angular CDK (drag-drop)
Relational DB	PostgreSQL
Document DB	MongoDB (LLM sessions)
Object Storage	Cloudflare R2 (S3-compatible)
LLM	Gemini (primary), OpenAI (fallback), provider-abstraction for future
Auth	Spring Security + OAuth2 Client — email/password, Google OAuth, GitHub OAuth, OpenID Connect
Git	JGit — local repo per site, optional GitHub/GitLab remote push
Infra	Docker Compose (dev), R2 + Cloudflare (hosting), Caddy/nginx (prod reverse proxy)

---

Build Phases

v0.1 — Auth & Foundation (Target: Weeks 1-3)

Goal: User can register, log in via email or OAuth, and create/manage sites and pages.

Backend

File	Action	Details
backend/build.gradle	Add	Spring Boot 3.x, deps: web, jpa, security, oauth2-client, oauth2-resource-server, validation, lombok, postgresql, testcontainers, aws-java-sdk-s3 (R2), springdoc-openapi, jgit
backend/settings.gradle	Add	Project name, plugin management
backend/src/main/resources/application.yml	Add	DB configs, JWT keys, OAuth client IDs/secrets, LLM keys, R2 credentials, git config
com/indie/IndieApplication.java	Add	Main class
com/indie/config/SecurityConfig.java	Add	SecurityFilterChain with JWT filter + OAuth2 login + OpenID Connect. Route permissions: /api/auth/** public, /api/** authenticated
com/indie/config/JwtConfig.java	Add	RS256 signing, access token 15min, refresh token 7d
com/indie/config/GitConfig.java	Add	Repos root path (/var/git/sites/), author name/email
com/indie/model/User.java	Add	id(UUID), email, password(bcrypt, nullable), name, avatarUrl, provider(LOCAL/GOOGLE/GITHUB/OPENID), providerId, emailVerified, createdAt, updatedAt
com/indie/model/Site.java	Add	id, userId, name, description, subdomain(unique), themeConfig(JSONB), status(DRAFT/PUBLISHED), publishedAt, createdAt, updatedAt
com/indie/model/Page.java	Add	id, siteId(FK), title, slug, seoTitle, seoDescription, orderIndex, createdAt
com/indie/model/Component.java	Add	id, pageId(FK), type(enum), config(JSONB), styles(JSONB), orderIndex
com/indie/repository/*.java	Add	JPA repositories for User, Site, Page, Component
com/indie/service/AuthService.java	Add	register, login, refreshToken, oauthLogin
com/indie/service/OAuth2UserService.java	Add	Maps Google/GitHub/OpenID user info to User entity
com/indie/controller/AuthController.java	Add	POST /api/auth/register, /login, /refresh, /logout
com/indie/controller/SiteController.java	Add	Full CRUD: GET/POST /api/sites, GET/PUT/DELETE /api/sites/{id}
com/indie/controller/PageController.java	Add	CRUD for pages within a site

Frontend

File	Action	Details
frontend/	Init	Angular 17 standalone, Angular Material, lazy routes, Tailwind CSS
src/app/auth/	Add	LoginComponent, RegisterComponent, OAuth callback handler, AuthService, AuthGuard, JWT interceptor
src/app/dashboard/	Add	DashboardComponent (list site cards), CreateSiteDialog, DeleteSiteDialog

Infrastructure

File	Action	Details
docker-compose.yml	Add	PostgreSQL, MongoDB, MinIO (local R2 mock), backend (8080), frontend (4200)

---

v0.2 — Drag-and-Drop Builder (Target: Weeks 4-6)

Goal: User can visually build a website by dragging components onto a canvas, editing their properties, styling via theme editor, and previewing live.

Backend

File	Action	Details
com/indie/controller/BuilderController.java	Add	GET /api/sites/{id}/pages (with nested components), PUT /api/sites/{id}/pages/{pageId}/components (batch save), GET/PUT /api/sites/{id}/theme
com/indie/service/BuilderService.java	Add	Validate component tree (type enum, config schema, max 50/page), save in transaction

Frontend

File	Action	Details
src/app/builder/builder.component.ts	Add	3-panel layout (palette 250px, canvas flex, properties 320px) via CSS Grid or mat-sidenav
src/app/builder/services/builder-state.service.ts	Add	BehaviorSubject store: components$, selectedComponentId$, themeConfig$, pages$. Methods: add, remove, update, reorder. Undo/redo stack (50 snapshots)
src/app/builder/services/auto-save.service.ts	Add	2s debounce → PUT batch save. "Saving..."/"Saved" indicator
src/app/builder/component-palette/	Add	PaletteComponent — Material list of 10 draggable component types, organized by category
src/app/builder/canvas/	Add	CanvasComponent — cdkDropList accepting drops, renders components in order, highlight on select, delete on hover
src/app/builder/property-panel/	Add	PropertyPanelComponent — dynamic form per type (config + styles sections). Material expansion panels
src/app/builder/renderer/	Add	Render components per type (heading, text, image, button, divider, gallery, video, contact_form, map, custom_html) — each takes config + styles as @Input()
src/app/builder/theme-editor/	Add	ThemeEditorComponent — color pickers, font selectors, spacing slider. Live preview updates
src/app/builder/preview/	Add	PreviewComponent — sandboxed <iframe> with srcdoc, responsive device toggles (desktop/tablet/mobile)
src/app/builder/builder-api.service.ts	Add	HTTP calls for save/load components, theme, pages

Component types: heading, text, image, button, divider, gallery, video, contact_form, map, custom_html

---

v0.3 — LLM Prompt-to-Site (Target: Weeks 7-8)

Goal: User types a description of their desired website → AI generates the full site structure (pages + components + theme) → user tweaks in builder or refines via another prompt.

Backend

File	Action	Details
com/indie/service/llm/LLMProvider.java	Add	Interface: generate(systemPrompt, userPrompt, options) → LLMResult. LLMResult: content, tokenUsage, model, latency
com/indie/service/llm/GeminiProvider.java	Add	Implements LLMProvider via Gemini API. Config: indie.llm.providers.gemini.api-key, model
com/indie/service/llm/OpenAIProvider.java	Add	Implements LLMProvider via OpenAI API. Config: indie.llm.providers.openai.api-key, model
com/indie/service/llm/LLMFactory.java	Add	Returns configured provider from indie.llm.active-provider, fallback chain
com/indie/dto/LLMOptions.java	Add	temperature, maxTokens, timeout, responseFormat
com/indie/dto/SiteStructure.java	Add	Top-level DTO: List<PageStructure> pages, ThemeConfig theme. Nested types for page and component
com/indie/dto/LLMResult.java	Add	content(String), tokenUsage, model, latencyMs
com/indie/model/LLMSession.java	Add	MongoDB document: userId, prompt, generatedStructure, acceptedAt, refinedPrompt, createdAt
com/indie/service/LLMService.java	Add	Orchestrator: prompt → LLM → parse → validate → return SiteStructure
com/indie/service/LLMResponseParser.java	Add	Parse LLM JSON output, handle markdown fences, malformed fields, partial extraction
com/indie/controller/LLMController.java	Add	POST /api/llm/generate (prompt→structure), POST /api/llm/refine (structure+prompt→refined). Rate limit: 10/hour/user
com/indie/config/RateLimitConfig.java	Add	Rate limiting via bucket4j
src/main/resources/prompts/site-generator.txt	Add	System prompt: schema definition + 2-3 few-shot examples

Frontend

File	Action	Details
src/app/llm-workspace/	Add	LLMWorkspaceComponent — textarea, "Generate" button, loading spinner with ETA, result preview summary, "Apply to Builder" button
src/app/llm-workspace/llm-session.service.ts	Add	Prompt history, refinement flow (original prompt + user edits + refinement → new generation)

---

v0.4 — Export, Git & Hosting (Target: Weeks 9-11)

Goal: User can publish their site as pure static files. Every publish creates a git commit. User can connect GitHub/GitLab for automatic pushes. Sites served at *.indie.com for free.

Backend

File	Action	Details
com/indie/service/RenderService.java	Add	Core render engine: renderSite(site), renderPage(site, page, components) → String, renderCss(theme, components) → String, renderJs() → String
com/indie/engine/templates/*.html	Add	Thymeleaf templates per component type + layout.html + head.html
com/indie/engine/StyleCompiler.java	Add	Theme → CSS custom properties at :root, component styles → CSS classes, responsive breakpoints
com/indie/engine/JsBundle.java	Add	Generates script.js: nav toggle, smooth scroll, lightbox, contact form handler, comment form handler. Minified
com/indie/service/ExportService.java	Add	export(siteId) → ZipOutputStream — full site directory + .git/
com/indie/controller/ExportController.java	Add	GET /api/sites/{id}/export → application/zip download
com/indie/service/GitService.java	Add	initRepo(siteId), commit(siteId, message), commitAndPush(siteId, message), getLog(siteId), rollback(siteId, commitHash), exportRepo(siteId)
com/indie/model/GitRemote.java	Add	JPA: id, siteId, provider(GITHUB/GITLAB), remoteUrl, encryptedToken, defaultBranch
com/indie/service/KeyManager.java	Add	SSH keypair generation per site, encrypted storage
com/indie/controller/GitController.java	Add	POST /api/sites/{id}/git/connect, /disconnect, GET /api/sites/{id}/git/status
com/indie/service/DeploymentService.java	Add	On publish: render → write to git working dir → GitService.commit → upload to R2 → return public URL
com/indie/controller/DeploymentController.java	Add	POST /api/sites/{id}/publish, /unpublish
com/indie/service/DomainService.java	Add	Skeleton: store custom domain mapping in Site entity, prepared for future TLS
com/indie/service/MediaService.java	Add	Upload to R2, validate type/size, resize
com/indie/controller/MediaController.java	Add	POST /api/media/upload, GET /api/media/{id}

Frontend

File	Action	Details
src/app/builder/git-settings/	Add	GitSettingsComponent — connect/disconnect GitHub/GitLab OAuth, select remote repo, connection status
src/app/builder/settings/	Add	SettingsComponent — site name, subdomain, export zip button, publish/unpublish buttons

Infrastructure

File	Action	Details
infra/cloudflare-worker.js	Add	Routes *.indie.com → R2 bucket indie-sites/{subdomain}/
docker-compose.prod.yml	Add	Production services: PostgreSQL, MongoDB, backend (×2), nginx, certbot

Git directory structure on server:

/var/git/sites/
  └── {siteId}/
      ├── .git/
      ├── index.html
      ├── about/index.html
      ├── style.css
      ├── script.js
      └── assets/

---

v0.5 — Social Features & Polish (Target: Weeks 12-13)

Goal: Minimal social features (comments, RSS) and final polish before public release.

Backend

File	Action	Details
com/indie/model/Comment.java	Add	JPA: id(UUID), siteId, pageId, authorName, authorEmail, content, isApproved, parentCommentId, createdAt
com/indie/controller/CommentController.java	Add	Public: POST /api/sites/{subdomain}/comments. Authenticated: GET/PUT/DELETE moderation
com/indie/service/RssService.java	Add	generateRss(siteId) → String — RSS 2.0 feed from site pages
com/indie/controller/RssController.java	Add	GET /api/feed/{subdomain} → application/rss+xml, 1h cache

Frontend

File	Action	Details
src/app/builder/settings/	Modify	Add git history panel (commit list, rollback button, download repo)
src/app/builder/components/comments-section/	Add	In-builder config (enable/disable, moderate) + renderer for generated sites

---

Infrastructure Architecture

                    ┌──────────────────────┐
                    │    Cloudflare CDN     │
                    │ *.indie.com → R2     │
                    └────────┬─────────────┘
                             │
                    ┌────────▼─────────────┐
                    │   Cloudflare R2       │
                    │ indie-sites bucket    │
                    │ /{subdomain}/*        │
                    └──────────────────────┘
                             ▲
                    ┌────────┴─────────────┐
                    │   Spring Boot API    │
                    │   (VPS / Docker)     │
                    └────────┬─────────────┘
                             │
              ┌──────────────┼──────────────┐
              │              │              │
     ┌────────▼───┐  ┌──────▼──────┐  ┌───▼────────┐
     │ PostgreSQL  │  │   MongoDB   │  │  Git Repos  │
     │ (users,     │  │ (LLM sess.) │  │ /var/git/   │
     │  sites,     │  └─────────────┘  └────────────┘
     │  pages,     │
     │  comps)     │
     └─────────────┘

---

LLM Provider Abstraction

// Adding a new provider = implement this interface + add config
public interface LLMProvider {
    LLMResult generate(String systemPrompt, String userPrompt, LLMOptions options);
    String getName();
}

// application.yml
indie:
  llm:
    active-provider: gemini
    fallback-provider: openai
    providers:
      gemini:
        api-key: ${GEMINI_API_KEY}
        model: gemini-2.0-flash
      openai:
        api-key: ${OPENAI_API_KEY}
        model: gpt-4o-mini

---

Key Design Decisions

1. Static output only — Generated sites are pure HTML/CSS/JS. No Angular/React dependency for end users. They own the output forever, no lock-in.

2. Git as source of truth — Every site is a git repository. Publish = commit. Rollback is a git checkout. Export includes full .git/ history.

3. Shared rendering — The same component renderers drive the builder preview AND the static export. What you see is what you get.

4. No billing in MVP — Subdomain hosting is free. No Stripe/PayPal code. Monetization (paid hosting, custom domains) is a post-MVP concern.

5. Incremental releases — Each v0.x is independently shippable. If timeline slips, ship what's done.

---

Validation Strategy

Release	What to Test
v0.1	Register, login (email + OAuth), refresh token, site CRUD, page CRUD, 401 on unauthenticated
v0.2	Drag → reorder → save → reload matches, theme change reflects in preview, undo/redo, all 10 component types render
v0.3	LLM generates valid SiteStructure JSON, generation loads into builder, refinement updates correctly, error handling (timeout, bad JSON)
v0.4	Exported zip opens in browser identically to preview, git init + commit works, git push to remote works, R2 upload succeeds, subdomain serves content
v0.5	Comment submit → approve → display, RSS validates, image upload + resize, rollback restores previous version

---

Risk Register

Risk	Likelihood	Mitigation
Scope creep (adding features mid-phase)	High	Strict feature freeze per v0.x; ship as-is
Drag-drop performance with many components	Medium	Cap at 50 components/page; virtual scroll if needed
LLM output quality inconsistent	Medium	Iterate on system prompt; template gallery fallback
Solo developer burnout	Medium	Realistic timeline; celebrate each release
LLM API costs	Low	Gemini-2.0-flash is free-tier friendly; rate limit 10/hour/user