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