AI-friendly code structure that turns ideas directly into code
Quick Start • Core Features • Architecture • Documentation • Contributing
🚧 This project is currently in very early development stage. Code structure may change at any time, but the goal is to be a production-ready starter for large commercial projects
🎯 This is an experimental attempt at AI-friendly software architecture
💡 Exploring how to make code structure more understandable and generatable by AI
Welcome to discuss and contribute, let's explore best practices for software development in the AI era together!
The core ideas and implementation approach of this project come from:
《Discussion on Possible Changes in Software Architecture and Collaboration Relationships in the AI Era》 ⭐
In the era of AI programming, traditional project architectures face challenges:
- ❌ Business rules scattered across code, AI needs to read massive amounts of code to understand intent
- ❌ Horizontal layered architecture makes it difficult for AI to locate functional boundaries
- ❌ Implicit domain knowledge requires repeated manual explanations
- ❌ Test-unfriendly design, automated tests are costly and flaky
Go-GenAI-Stack rethinks how code is organized:
| Traditional Architecture | Go-GenAI-Stack (Vibe-Coding-Friendly) |
|---|---|
| Business rules hidden in code | Explicit knowledge files (rules.md, glossary.md) |
| Layered by tech stack | Vertically split by business domain |
| Describe flow with code | Declare use cases with YAML (usecases.yaml) |
| AI needs to read thousands of lines | AI reads a few structured files to understand |
| Manual frontend-backend type sync | Go → TypeScript automatic sync |
| Flaky tests and unstable selectors | Playwright-friendly design + data-test-id convention + Docker E2E env |
💡 Vibe Coding: Express your ideas, AI understands business logic, directly generates code that follows rules.
This project makes AI a true programming partner, not just a code completion tool.
This is a production-ready full-stack Starter with a complete Task domain as a best practice example:
- ✅ Ready to use: If you need task management functionality
- ✅ Use as template: Map to your business (Product, Order, Article...)
- ✅ Learn from it: Understand how to build AI-friendly architecture
-
Backend Architecture inspired by Coze Studio:
- Domain-Driven Design centered on LLM orchestration
- Plugin-first and extensibility priority
- Declarative workflows (usecases.yaml)
-
Mobile Architecture inspired by Bluesky Social App:
- React Native best practices
- Native-level performance optimization
- Cross-platform component design
Go-GenAI-Stack/
├── backend/ # Backend (Go + Hertz + DDD)
│ ├── cmd/ # Application entry
│ │ └── server/ # HTTP Server entry
│ ├── domains/ # Domain layer (Domain-First)
│ │ ├── task/ # Task domain (example implementation) ★
│ │ │ ├── handlers/ # HTTP adapter layer
│ │ │ ├── service/ # Business logic layer
│ │ │ ├── model/ # Domain model
│ │ │ └── ... # Other components
│ │ └── shared/ # Shared components
│ ├── infrastructure/ # Infrastructure layer
│ │ ├── bootstrap/ # Bootstrap
│ │ ├── persistence/ # Persistence (Postgres, Redis)
│ │ ├── middleware/ # Middleware
│ │ ├── config/ # Configuration management
│ │ └── database/ # Database Schema
│ ├── pkg/ # Reusable packages
│ │ └── validator/ # Validator
│ ├── migrations/ # Database migrations
│ │ ├── atlas/ # Atlas migration files & config
│ │ └── seed/ # Seed data
│ ├── shared/ # Shared code
│ │ └── errors/ # Error definitions
│ └── scripts/ # Development scripts
├── frontend/ # Frontend Monorepo
│ ├── web/ # React Web application
│ ├── mobile/ # React Native mobile application
│ └── shared/ # Frontend shared code
│ ├── types/ # TypeScript type definitions
│ ├── utils/ # Utility functions
│ └── constants/ # Constants
├── docs/ # Project documentation
├── docker/ # Docker configuration
└── scripts/ # Project-level scripts
|
Each domain requires 6 structured files: AI only needs to read these 6 files to understand complete business logic! |
# usecases.yaml
CreateTask:
description: "Create new task"
steps:
- ValidateInput
- GenerateTaskID
- SaveTask
- PublishEvent
errors:
- TASK_TITLE_EMPTY
- TASK_ALREADY_EXISTSAI reads YAML → Automatically generates Handler + Tests |
| Feature | Traditional DDD | Vibe-Coding-Friendly DDD | Improvement |
|---|---|---|---|
| AI Understanding Speed | Need to read thousands of lines | Only read 6 structured files | 10x ⚡ |
| Onboarding Time | 2-3 days | 30 minutes (starting from README) | 5x 🚀 |
| Maintenance Cost | Search across multiple directories | Self-contained (one directory) | -70% 💰 |
| Use Case Changes | Manually change code + tests | Change YAML → AI auto-generates | 3x ⚡ |
| Type Safety | Manual frontend-backend sync | Go → TS automatic sync | 100% ✅ |
In AI-assisted development, testability determines how fast AI-generated code can be verified. This project is optimized for automation:
- Frontend Playwright-friendly: Mandatory
data-test-idon all interactive elements; stable routes/state to reduce flakiness; selectors never rely on styling classes. - Isolated E2E environment: Docker spins dedicated Postgres (:5433) + Backend (:8081) so dev and E2E can run in parallel;
pnpm e2e:all= setup → test → teardown. - Stable fixtures: Seed data and fixed test accounts; shared Playwright fixtures/helpers to avoid magic strings.
- Fast unit feedback: Vitest + happy-dom + thread pool;
pnpm test:watchfor second-level feedback,pnpm test:coveragefor reports. - Directory as contract: Feature-local
__tests__beside hooks/stores/api/components so humans/AI can locate behaviors quickly. - CI friendly: E2E triple caching (pnpm store / Playwright browsers / Docker layers); backend
./backend/scripts/test_all.shsupports coverage output, reducing pipeline time.
Goal: close the loop of “AI generates → automation validates → quick fix” with minimal human regression effort.
✅ domains/task/ # Organized by business domain
├── model/ # Domain model
├── service/ # Business logic
├── repository/ # Data access
├── handlers/ # HTTP adapter layer
└── tests/ # Tests
❌ Traditional layering (hard to locate functionality):
├── controllers/ # All domains mixed together
├── services/ # All services mixed together
└── repositories/ # All repositories mixed together
Each domain is independent:
- ✅ Can be understood, modified, and tested separately
- ✅ Reduces cognitive load (focus on one domain)
- ✅ Easy parallel development (different teams for different domains)
// Handler layer (thin): Only HTTP adaptation
func CreateTaskHandler(c *app.RequestContext) {
var req dto.CreateTaskRequest
c.BindAndValidate(&req)
// Call Service layer
output, err := taskService.CreateTask(ctx, input)
c.JSON(200, response)
}
// Service layer (thick): Business logic ⭐
func (s *TaskService) CreateTask(input CreateTaskInput) {
// 1. Validate business rules
// 2. Create domain object
// 3. Persist
// 4. Publish event
}
// Repository layer: Data access (database/sql, no ORM)
func (r *TaskRepo) Create(task *Task) error {
query := `INSERT INTO tasks (...) VALUES (...)`
_, err := r.db.ExecContext(ctx, query, ...)
return err
}# 1️⃣ You: Add new use case in usecases.yaml
vim backend/domains/task/usecases.yaml
# 2️⃣ AI: Reads explicit knowledge files
# - README.md (understand domain boundaries)
# - glossary.md (understand terminology)
# - rules.md (understand business rules)
# - usecases.yaml (understand use case flow)
# 3️⃣ AI: Auto-generates code
# ✅ handlers/new_usecase.handler.go
# ✅ service/task_service.go (new method)
# ✅ http/dto/new_usecase.go
# ✅ tests/new_usecase.test.go
# 4️⃣ You: Run tests and commit
./backend/scripts/test_all.sh
git commit -m "feat(task): add new usecase"True Vibe Coding: You only need to express intent, AI completes the implementation!
| Tool | Purpose | Command |
|---|---|---|
| Atlas | Database Schema management | cd backend/database && make diff/apply |
| Type Sync | Go → TypeScript type sync | ./scripts/sync_types.sh all |
| Testing | Unit + Integration + E2E | ./backend/scripts/test_all.sh / pnpm test / pnpm e2e:all |
| Linting | Code quality check | ./backend/scripts/lint.sh --fix |
| Docker | One-click full environment | ./scripts/quickstart.sh |
Complete three pillars observability solution (with toggle control):
|
🔍 Structured Logging
|
📈 Prometheus Metrics
|
🔗 Distributed Tracing
|
// One-click toggle (via config file)
observability:
logging:
enabled: true # Logging
metrics:
enabled: true # Metrics
tracing:
enabled: true # TracingAccess:
- Health check:
http://localhost:8080/health - Prometheus:
http://localhost:8080/metrics - Grafana:
http://localhost:3000(full monitoring)
📖 Detailed docs: Observability Guide
The easiest way to get started:
# 1️⃣ Clone the project
git clone https://github.com/erweixin/Go-GenAI-Stack.git
cd Go-GenAI-Stack
# 2️⃣ One-click start (Backend + Database)
./scripts/quickstart.shThis script will:
- ✅ Check dependencies (Go, Docker)
- ✅ Setup environment variables (copy from .env.example if needed)
- ✅ Start PostgreSQL and Redis (Docker)
- ✅ Run database migrations (Atlas)
- ✅ Load seed data
- ✅ Start backend server
Access services:
- 🔗 Backend API:
http://localhost:8080/api - ❤️ Health check:
http://localhost:8080/health - 📊 Prometheus Metrics:
http://localhost:8080/metrics
For full-stack development:
# 1. Start backend (in one terminal)
./scripts/quickstart.sh
# 2. Start frontend (in another terminal)
cd frontend
pnpm install
cd web
pnpm devAccess:
- 🌐 Frontend Web:
http://localhost:5173 - 🔗 Backend API:
http://localhost:8080/api
Start complete production environment with monitoring:
# Start all services (Backend + Monitoring)
./scripts/start-all.shAccess services:
- 🔗 Backend API:
http://localhost:8080 - 📊 Grafana:
http://localhost:3000(admin/admin) - 🔍 Jaeger:
http://localhost:16686 - 📈 Prometheus:
http://localhost:9090 - 🐛 Sentry:
http://localhost:9000
Note: Frontend needs to be built and deployed separately. See Frontend README for build instructions.
Click to expand detailed steps
- Go 1.23+
- Node.js 22.0+
- pnpm 8.0+
- Docker & Docker Compose (for databases)
- Atlas (Schema management)
# Install Atlas
curl -sSf https://atlasgo.sh | sh# Start PostgreSQL and Redis
cd docker
docker-compose up -d postgres redis
# Wait for databases to be ready
docker-compose pscd backend
# Install dependencies
go mod download
# Apply database migrations
cd database
make apply
# Load seed data (optional)
make seed
# Start backend server
cd ..
go run cmd/server/main.goBackend will start at http://localhost:8080
cd frontend
# Install dependencies
pnpm install
# Start Web application
cd web
pnpm dev # http://localhost:5173
# Or start Mobile application (optional)
cd ../mobile
pnpm start# Check backend health
curl http://localhost:8080/health
# Check frontend
open http://localhost:5173📖 More startup options: Docker Deployment Guide
# 1. Declare use case
vim backend/domains/task/usecases.yaml
# 2. AI generates code (or write manually)
# - handlers/new_usecase.handler.go
# - service/task_service.go
# - http/dto/new_usecase.go
# - tests/new_usecase.test.go
# 3. Run tests
./backend/scripts/test_all.shDetailed guide: Quick Reference |
cd backend/database
# Generate migration
make diff NAME=add_field
# Apply migration
make apply
# Check status
make statusDetailed guide: Database Management |
# Sync single domain
./scripts/sync_types.sh task
# Sync all domains
./scripts/sync_types.sh allGenerated types: Detailed guide: Type Sync |
# 1. Format + check
./backend/scripts/lint.sh --fix
# 2. Run tests
./backend/scripts/test_all.sh --coverage
# 3. Commit
git commit -m "feat(task): add feature"Follow Conventional Commits specification |
|
📚 Complete documentation index: docs/INDEX.md
|
Language & Framework
Data Storage
Observability
Toolchain
|
Web Application
Mobile Application
Monorepo
|
Containerization
Monitoring & Observability
Database Management
Development Tools
|
|
🏗️ Core Architecture
🔧 Infrastructure
|
📊 Observability
🛠️ Development Tools
|
This project uses the Task domain as an example. You can:
|
If you need task management functionality Deploy immediately |
Understand Vibe-Coding-Friendly DDD Master best practices |
Replace with your domain Product, Order, Customer... |
Locations marked with Extension point in code can be extended:
| Extension Point | Description | Status |
|---|---|---|
| Application Layer | Cross-domain orchestration (needed for multi-domain collaboration) | 📖 Guide |
| LLM Integration | Integrate OpenAI, Claude, etc. | 🔌 Interface reserved |
| Event Bus | Switch from in-memory to Redis/Kafka | 🔌 Interface reserved |
| JWT Authentication | Complete token validation and refresh | 🔌 Interface reserved |
| ✅ Completed | ||
| ✅ Completed |
|
|
Welcome to share your ideas in Discussions!
We welcome all forms of contributions! ⭐ Star this project to show support.
|
🐛 Found an issue?
💬 Have an idea?
|
🔧 Want to contribute code? # 1. Fork and clone
git clone https://github.com/erweixin/Go-GenAI-Stack.git
# 2. Create branch
git checkout -b feat/amazing-feature
# 3. Commit (follow Conventional Commits)
git commit -m 'feat(task): add amazing feature'
# 4. Push and create PR
git push origin feat/amazing-feature |
Use Conventional Commits:
feat(domain): New feature
fix(domain): Bug fix
docs: Documentation update
refactor(domain): Refactoring
test(domain): Test
chore: Build/toolchain
| data-test-id + isolated Docker E2E env | go vet + staticcheck | Required files complete | usecases.yaml coverage |
If this project helps you, please give it a ⭐ Star!
|
Complete documentation |
Share ideas and questions |
Report bugs and feature requests |
- 《Discussion on Possible Changes in Software Architecture and Collaboration Relationships in the AI Era》 ⭐ - Core Philosophy Source: Discusses AI-era software architecture from the perspective of "productivity determines production relations", proposing core concepts like domain-first, self-contained, and explicit knowledge
- Coze Studio - LLM orchestration platform, inspired the declarative workflow design of this project
- Bluesky Social App - React Native best practices reference
- CloudWeGo Hertz - High-performance HTTP framework
- Eino Framework - ByteDance LLM framework
- Atlas - Database Schema management
- Domain-Driven Design - Domain-Driven Design
This project is licensed under the MIT License.
If this project helps you, please give it a ⭐ Star!
Made with ❤️ by Go-GenAI-Stack Team
Version: v0.1.0 | Status: 🚀 Active Development | Last Updated: 2025-12-02