Lovable 分布式微服务架构解析：AI 生成全栈 Web 应用

Describe what you want to build in natural language — Lovable generates, deploys, and previews working web applications in real time.

Table of Contents

• Overview
• Demo
• Architecture
  • System Architecture
  • Code Generation and Code Execution
  • AI Code Generation Flow
  • Code Execution Architecture
  • Database Schema
  • CI/CD Pipeline
• Key Features
• Tech Stack
• Microservices Overview
• API Endpoints
• Getting Started
  • Prerequisites
  • Installation
  • Environment Variables
• Running the Project
  • Local Development
  • Kubernetes Deployment
• Project Structure
• Contributing
• License

Overview

Lovable is a full-stack AI-powered application generation platform built as a distributed microservices system. Users describe applications in natural language through an interactive chat interface, and the platform's AI engine generates complete web applications — including HTML, CSS, and JavaScript — that are immediately deployable as live previews on Kubernetes.

The platform supports multi-user collaboration, subscription-based billing via Stripe, token usage tracking, and event-driven file storage. It is designed from the ground up for cloud-native deployment with Kubernetes, service discovery, and CI/CD via GitHub Actions that automatically build and push Docker images to Docker Hub.

Demo

Link- https://youtu.be/B6HJi5CeOBk

Architecture

System Architecture

Lovable follows a microservices architecture with six Spring Boot services, a React frontend, and shared infrastructure components.

Component breakdown:

Data flow:

1. The React frontend sends requests to the API Gateway.
2. The gateway validates the JWT token and routes to the appropriate microservice.
3. Services communicate via Feign clients (synchronous) and Kafka (asynchronous).
4. All services fetch shared configuration from the Config Service, which pulls from a Git repository.
5. Generated files are stored in MinIO, preview URLs are cached in Redis, and persistent data resides in PostgreSQL.

Code Generation and Code Execution

Lovable is architecturally divided into two distinct domains: Code Generation and Code Execution. These two domains are implemented by separate microservices with clear responsibilities, enabling independent scaling and evolution.

Code Generation — Intelligence Service

The Intelligence Service (Port 8083) is the brain of the platform. It handles everything related to AI-powered code creation:

• Natural Language Understanding — Receives user prompts describing the desired application in plain English.
• Context Assembly — Fetches the current file tree, existing file contents, and package.json from the Workspace Service via internal Feign clients (InternalWorkspaceController). The package.json is injected into the LLM context as PACKAGE_JSON so the AI knows which third-party packages are already available.
• System Prompt Construction — Builds a comprehensive prompt that combines the user's request with the project's current state, ensuring context-aware and incremental code changes. The AI is instructed to only import packages already listed in package.json, preventing dependency bloat.
• LLM Integration — Sends the assembled prompt to OpenAI's API via Spring AI (AiGenerationServiceImpl). The LLM generates complete HTML, CSS, and JavaScript code.
• Streaming Response — Returns the AI's response as a real-time stream using Server-Sent Events (SSE), so the user sees code appear character-by-character in the chat interface.
• Chat History — Persists every message (user prompts and AI responses) in PostgreSQL for conversation continuity across sessions.
• Token Tracking — Logs token consumption per message for usage monitoring and quota enforcement.
• Auth Header Propagation — Passes the user's Authorization header through to Workspace Service internal calls, ensuring proper permission checks during context assembly.

Code Execution — Workspace Service

The Workspace Service (Port 8082) is the engine that makes generated code runnable. It handles everything related to project management, file storage, and live preview deployment:

• Project Management — Full CRUD for projects, including creation, updates, and soft-deletion.
• File Tree Management — Stores and retrieves the hierarchical file structure for each project. Files are stored as objects in MinIO (S3-compatible), with metadata in PostgreSQL (ProjectFile entity).
• Kafka Consumer — Listens for file storage events published by the Intelligence Service after AI generation. Consumes the event, parses the generated files, and stores them in MinIO.
• Preview Deployment — When a user triggers a deployment (POST /projects/{id}/deploy), the service uses the Fabric8 Kubernetes Client (DeploymentService.java) to create an isolated pod with runner and syncer containers.
• Runner Pod Lifecycle — Manages the full lifecycle of preview pods: creation, status monitoring, and cleanup. Each pod serves the generated files via an HTTP server. Supports pod resumption for existing deployments.
• Runner Image — Uses the stock node:22-alpine image for preview pods.
• Serialized npm Installs — Uses file-based locking (/tmp/preview-install.lock) to prevent concurrent npm install operations within a pod, avoiding race conditions when files update rapidly.
• Preview Status API — Exposes GET /projects/{id}/preview-status endpoint that returns the pod's current status (CREATING, RUNNING, FAILED, TERMINATED), enabling the frontend to poll and display real-time preview readiness.
• Multi-User Collaboration — Manages project members with role-based access (EDITOR/VIEWER) via the ProjectMember entity.

How They Work Together

User Prompt → Intelligence Service (Code Generation)
                    │
                    ├─ Fetches file tree from Workspace Service
                    ├─ Calls LLM → Streams code back
                    └─ Publishes generated files to Kafka
                           │
Workspace Service (Code Execution) ← Consumes from Kafka
                    │
                    ├─ Stores files in MinIO
                    └─ Deploys preview pod on Kubernetes

The Intelligence Service focuses purely on creating code, while the Workspace Service focuses purely on storing and running it. This separation ensures that:

• AI generation can scale independently of preview deployments.
• File storage and preview infrastructure are centralized in one service.
• Each service has a single, well-defined responsibility following the Single Responsibility Principle.

AI Code Generation Flow

The AI generation pipeline transforms a natural language prompt into deployable code through a multi-step process.

Step-by-step flow:

1. User Prompt — The user types a description of the desired application in the React frontend chat interface.
2. Request Routing — The request travels through the API Gateway to the Intelligence Service (ChatController.java).
3. Context Assembly — The service fetches the current file tree, existing file contents, and package.json from the Workspace Service via internal Feign clients. The Authorization header is propagated to ensure proper permission checks.
4. System Prompt Construction — The service builds a system prompt that includes:
   • The current file tree structure.
   • Existing file contents for context-aware generation.
   • The project's package.json as PACKAGE_JSON context, so the AI knows which packages are available.
   • Project-specific constraints and guidelines, including a rule to only import packages already listed in package.json.
5. LLM Call — The assembled prompt is sent to OpenAI's API via Spring AI (AiGenerationServiceImpl.java).
6. Streaming Response — The LLM response streams back as SSE events to the frontend in real time.
7. File Parsing — The streamed response is parsed to extract code blocks with file paths.
8. File Storage — Parsed files are published to Kafka, where the Workspace Service consumes the event and stores them in MinIO.
9. Preview Deployment — The Workspace Service triggers a Kubernetes deployment, creating an isolated pod for the updated preview. The frontend polls the preview status endpoint to show real-time readiness.

Code Execution Architecture

Each project's live preview runs in an isolated Kubernetes pod, ensuring complete separation between user projects.

Architecture details:

• Runner Pod — When a project is deployed (POST /projects/{id}/deploy), the Workspace Service creates a dedicated Kubernetes pod containing two containers:
  • Runner container: Uses the stock node:22-alpine image. On startup, it runs npm install to add project dependencies.
  • Syncer container: Uses pgsty/mc:latest to fetch the latest files from MinIO via mc mirror --watch, keeping the runner's file system synchronized in real time.
  • Dependency Resolution — The runner uses file-based locking to serialize npm install operations, preventing race conditions. It also watches for package.json changes and auto-reinstalls dependencies when new packages are added by the AI.
  • Reverse Proxy — A dedicated proxy service (lovable-me-proxy) routes incoming preview requests to the correct runner pod based on the subdomain. Returns HTTP 503 with Retry-After: 10 header when a preview is still starting.
  • Redis URL Mapping — The mapping between preview subdomains ({projectId}.previews.lovable.in) and pod IPs is stored in Redis for fast lookups.
  • Resource Limits — Runner pods are configured with higher CPU limits (up to 2000m) and memory limits (2Gi) to handle npm installs and Vite dev server efficiently.
  • Network Policies — Kubernetes network policies isolate preview pods from the core services, ensuring security boundaries.
  • Preview Status Polling — The frontend polls GET /projects/{id}/preview-status every 5 seconds (up to 10 minutes) to display real-time preview readiness, showing a loading state while the pod starts and notifying the user if the preview terminates.

Deployment command in code: DeploymentService.java uses the Fabric8 Kubernetes Client to programmatically create and manage preview pods.

Database Schema

The platform uses PostgreSQL with separate schemas per microservice, following database-per-service pattern.

Entities by service:

The pgvector extension is available for potential semantic search and embedding-based features.

CI/CD Pipeline

The project uses GitHub Actions for continuous integration. Each service has a dedicated workflow that automatically builds and pushes Docker images to Docker Hub on every push to the main branch.

Build workflow (per service):

1. Code Push — Developer pushes changes to the main branch, triggering the GitHub Actions workflow.
2. Path Filtering — Each workflow monitors specific paths (e.g., account-service/**, common-lib/**) to avoid unnecessary builds.
3. JDK 25 Setup — The workflow configures Temurin JDK 25 with Maven caching.
4. Common Lib Install — For services depending on common-lib (account, workspace, intelligence), it is built and installed to the local Maven repository first.
5. Service Build — The target service is packaged with mvn clean package -DskipTests.
6. Docker Image Build & Push — Backend services use the Jib Maven plugin to build and push images to Docker Hub. The frontend and proxy use Docker Buildx. All images are tagged with the git SHA and latest.

Workflow files: Seven dedicated workflows exist in .github/workflows/, one per deployable component:

Deployment to GKE: After images are pushed to Docker Hub, deploy them to GKE using kubectl apply with the manifests in k8s/.

Additional documentation:

• 📄 Feature Overview & API Summary — Core features, API endpoints, Stripe payments, quota management, and rate limiting.
• 📄 Detailed Microservice Architecture Reference — Service responsibilities, dependencies, entities, security model, Feign clients, and K8s deployment guide.
• 📄 Complete API Endpoint Reference — Full REST API documentation with request/response examples.

Key Features

• AI-Powered Code Generation — Natural language to production-ready code with real-time streaming responses via Server-Sent Events.
• Live Preview Deployments — Each project gets an isolated Kubernetes pod with a unique subdomain for instant preview.
• Multi-User Collaboration — Invite team members to projects with role-based access control (EDITOR/VIEWER).
• Stripe Subscription Billing — Integrated payment processing with FREE (10 projects, 50K tokens) and PRO plans, checkout sessions, and customer portal.
• Token Usage Tracking — Per-user token consumption logging with plan-based quota enforcement.
• File Tree Management — Hierarchical file storage in MinIO with S3-compatible API, supporting nested directories.
• Chat History — Persistent conversation history per project, stored in PostgreSQL.
• Event-Driven Architecture — Kafka-based async file storage and inter-service communication.
• Git-Backed Configuration — Centralized config management via Spring Cloud Config Server with Git as the source of truth.
• Automated CI/CD — GitHub Actions automatically build and push Docker images to Docker Hub on every push to main.
• Service Discovery — Netflix Eureka for dynamic microservice registration and discovery.
• JWT-Based Security — Stateless authentication with shared secret validation across all services.

Tech Stack

Backend

Frontend

Infrastructure

CI/CD

Microservices Overview

API Endpoints

All public endpoints are accessed through the API Gateway at api.lovable.in. Internal endpoints are used for inter-service communication.

Authentication (Account Service)

Billing (Account Service)

Projects (Workspace Service)

Files (Workspace Service)

Collaboration (Workspace Service)

Chat & AI (Intelligence Service)

Internal Service-to-Service Endpoints

Getting Started

Prerequisites

• Java 25 (Temurin recommended)
• Maven 3.9+ (or use bundled mvnw)
• Node.js 22+ with npm
• Docker & Docker Compose — for local infrastructure services
• kubectl — for Kubernetes interactions

Installation

1. Clone the Repository

git clone https://github.com/<your-username>/lovable.git
cd lovable

2. Configure Environment Variables

Edit the .env file in the project root and adjust values for your environment.

3. Start Infrastructure Services

docker compose up -d

This starts PostgreSQL (port 9010), MinIO (ports 9000/9001), Redis (port 6379), and Kafka (port 29092).

4. Install Common Library

cd common-lib
./mvnw clean install -DskipTests
cd ..

5. Start Microservices

Start each service in order (each in a separate terminal):

# Discovery Service (must start first)
cd discovery-service && ./mvnw spring-boot:run

# Config Service
cd config-service && ./mvnw spring-boot:run

# Account Service
cd account-service && ./mvnw spring-boot:run

# Workspace Service
cd workspace-service && ./mvnw spring-boot:run

# Intelligence Service
cd intelligence-service && ./mvnw spring-boot:run

# API Gateway
cd api-gateway && ./mvnw spring-boot:run

6. Start the Frontend

cd lovable-frontend
npm install
npm run dev

The frontend will be available at http://localhost:5173.

Environment Variables

The .env file configures all infrastructure and service connections:

Services import their configuration from the Config Service, which pulls from the Git repository specified by GITHUB_URI.

Running the Project

Local Development

Infrastructure only:

docker compose up -d

All services with hot reload:

Start each microservice with ./mvnw spring-boot:run in separate terminals. The frontend runs with Vite's dev server for HMR.

Build for production:

# Backend services
cd <service-name> && ./mvnw clean package -DskipTests

# Frontend
cd lovable-frontend && npm run build

Kubernetes Deployment

The project includes complete Kubernetes manifests in the k8s/ directory for deployment to GKE.

1. Create Namespaces

kubectl apply -f k8s/infra/namespaces.yaml

2. Deploy Core Infrastructure

# Network policies for core services
kubectl apply -f k8s/infra/core-network-policies.yaml

# Preview network policies
kubectl apply -f k8s/infra/preview-network-policies.yaml

3. Deploy Services

kubectl apply -f k8s/services/discovery-service.yaml
kubectl apply -f k8s/services/config-service.yaml
kubectl apply -f k8s/services/account-service.yaml
kubectl apply -f k8s/services/workspace-service.yaml
kubectl apply -f k8s/services/intelligence-service.yaml
kubectl apply -f k8s/services/api-gateway.yaml
kubectl apply -f k8s/services/frontend.yaml

4. Configure Ingress

kubectl apply -f k8s/infra/ingress.yaml

The ingress routes traffic as follows:

5. Deploy Runner Pool

kubectl apply -f k8s/infra/runner-pool.yaml

6. Verify Deployment

kubectl get pods -n lovable-core
kubectl get ingress -n lovable-core

CI/CD: Pushing to main automatically triggers the corresponding GitHub Actions workflow, which builds the Docker image with Jib and pushes it to Docker Hub. Each workflow monitors its service's directory path plus common-lib/** for dependency changes.

Project Structure

lovable/
├── account-service/          # User auth, JWT, Stripe billing, subscriptions
├── api-gateway/              # Spring Cloud Gateway, JWT validation, routing
├── common-lib/               # Shared library: JWT filter, DTOs, enums, exceptions
├── config-service/           # Spring Cloud Config Server (Git-backed)
├── discovery-service/        # Netflix Eureka service registry
├── intelligence-service/     # AI chat, SSE streaming, LLM integration (OpenAI)
├── workspace-service/        # Projects, files (MinIO), K8s previews, collaboration
├── lovable-frontend/         # React 18 + TypeScript + Vite + Tailwind CSS
├── k8s/                      # Kubernetes manifests
│   ├── infra/                # Namespaces, ingress, network policies, runner pool
│   ├── services/             # Deployment manifests for each microservice
│   ├── proxy/                # Preview reverse proxy configuration
│   ├── stateful/             # StatefulSet definitions
├── docs/                     # Architecture diagrams, PDFs, and demo video
├── .github/workflows/        # GitHub Actions CI/CD workflows
├── docker-compose.yml        # Local infrastructure (PostgreSQL, MinIO, Redis, Kafka)
└── .env                      # Environment variables