LingJingWanXiang (LJWX) Project Template

Overview

The LingJingWanXiang (灵境万象) project template is a standardized development framework designed for full-stack applications using Spring Boot, FastAPI, or Vue3, with deployment through GitOps using Argo CD and Kubernetes. The template provides a unified development workflow with built-in verification and deployment processes.

The project follows an opinionated architecture that enforces consistent engineering practices across different technology stacks. It uses ljwx.yaml as the single source of truth for all project configuration, which is used to generate Helm values, ArgoCD Application manifests, and environment files.

Supported Stacks

• Spring Boot: Java-based backend with embedded database and cache support
• FastAPI: Python-based backend with asynchronous capabilities
• Vue3: Modern frontend built with Vue.js 3 and Vite

Project Structure

ljwx-template/
├── ljwx.yaml                 # Single source of truth for project configuration
├── init_project.sh          # Generates configuration files from ljwx.yaml
├── verify.sh                # Validates the project template and ensures deployability
├── start_all.sh             # Local development startup script
├── helm/                    # Helm chart for Kubernetes deployment
├── argo/                    # ArgoCD Application manifests
├── .env.example             # Template for environment variables
├── PROMPT_BLUEPRINT.md      # Detailed development guidelines and constraints
├── QUICK_START.md           # Comprehensive quick start guide
├── TEMPLATE_DOD.md          # Template acceptance criteria
├── VARIABLES.md             # Variable dictionary and mappings
└── README.md               # This file

Getting Started

Prerequisites

The following tools must be installed:

• git
• docker
• docker-compose
• kubectl
• helm (>= 3.9)
• Optional but recommended: yq, jq

Quick Start

1. Configure Your Project

   Edit ljwx.yaml with your project details:

   appName: your-app-name
   stack: springboot            # springboot | fastapi | vue3
   namespace: your-namespace
   
   image:
     repo: your-registry/your-app
     tag: latest
   
   domain:
     host: your-domain.com
     tlsSecret: your-tls-secret
   
   profile: docker              # spring profile / fastapi env
   
   infra:
     mysqlSecret: your-mysql-secret
     mysqlDatabase: your_database
     redisSecret: your-redis-secret
     redisDb: "0"
   
   port: 8080
   

2. Initialize Configuration

   ./init_project.sh
   

   This script generates:

   • helm/values.yaml from helm/values.yaml.tpl
   • argo/application.yaml from argo/application.yaml.tpl (if exists)
   • .env from the extracted variables

3. Verify Template

   ./verify.sh
   

   The verification process checks:

   • ljwx.yaml format and required fields
   • Helm template renders without errors
   • start_all.sh --check passes (if no app exists, it may fail - expected)

Configuration Structure

ljwx.yaml (Single Source of Truth)

This is the only place for project configuration. All other configuration files are generated from this file.

Field	Required	Description
appName	✅	Application name
stack	✅	Technology stack (springboot/fastapi/vue3)
namespace	✅	Kubernetes namespace
image.repo	✅	Docker image repository
image.tag	✅	Docker image tag
domain.host	✅	Application domain
domain.tlsSecret	✅	TLS secret name
profile	✅	Runtime profile
port	✅	Service port
infra.mysqlSecret	✅ (for Spring Boot)	MySQL secret name
infra.mysqlDatabase	✅ (for Spring Boot)	MySQL database name
infra.redisSecret	✅ (for Spring Boot)	Redis secret name
infra.redisDb	✅ (for Spring Boot)	Redis database number

Generated Files

• helm/values.yaml: Kubernetes deployment values
• argo/application.yaml: ArgoCD Application manifest
• .env: Local environment variables

Local Development

Starting the Application Locally

# Start the application locally
./start_all.sh

# Check if the application can start (used by verify.sh)
./start_all.sh --check

# Build the application (if needed)
./start_all.sh --build

Supported Commands

• --check: Verify dependencies and configuration without starting the application
• --build: Build the application artifacts
• No arguments: Start the application in foreground mode

ArgoCD Integration

The template generates ArgoCD Application manifests following the single source of truth principle. The manifests are located in argo/application.yaml and follow template 1 (single source with parameters).

Development Conventions

Architecture Principles

• ljwx.yaml is the only place for project configuration
• No hardcoded values in Helm/Argo templates
• All configuration must be traceable back to ljwx.yaml
• GitOps (ArgoCD) is the only production deployment method
• Infrastructure is consumed, not created by applications

Project Structure Requirements

• All projects must provide start_all.sh script
• OpenAPI is the source of truth for APIs
• Each project must have its own Helm chart
• Database migrations must be versioned (Flyway/Liquibase)
• Applications must be observable (metrics, logs, traces)

Helm Charts

The template includes complete Helm charts for all supported stacks:

• Spring Boot: Complete chart with database migration job (Flyway)
• FastAPI: Service with optional database and Redis support
• Vue3: Static site served with Nginx

Best Practices

1. Configuration Management

   • Always update ljwx.yaml as the single source of truth
   • Never modify generated files directly
   • Rerun ./init_project.sh after any changes to ljwx.yaml

2. Verification

   • Run ./verify.sh after making configuration changes
   • Ensure all verification steps pass before committing

3. GitOps

   • Follow the established workflow: ljwx.yaml → init_project.sh → ArgoCD
   • Keep infrastructure configuration separate from application logic

4. Security

   • Store sensitive information in Kubernetes secrets
   • Use infrastructure namespace services only
   • Never commit credentials to the repository

Template Validation

The template includes a comprehensive validation process that ensures:

• All required fields in ljwx.yaml are present
• Generated files are syntactically correct
• Helm templates render without errors
• Application configuration is consistent

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Ensure all verification steps pass
5. Submit a pull request

License

This project is licensed under the terms specified in the repository.