bamort/template/README.md

MyApp Template

A full-stack web application template based on Go + Vue.js, providing authentication, user management, i18n, and a generic CRUD example module.

Technology Stack

Layer	Technology
Backend	Go 1.25 + Gin + GORM
Database	MariaDB (prod) / SQLite (test)
Frontend	Vue 3 + Vite + Pinia + vue-i18n
HTTP Client	Axios
Auth	JWT tokens
Dev Reload	Air (Go) + Vite HMR (Vue)
Containers	Docker + Docker Compose

Project Structure

template/
├── backend/
│   ├── cmd/main.go           # Entry point
│   ├── config/               # Environment configuration
│   ├── database/             # GORM + DB setup + migrations
│   ├── logger/               # Structured logger
│   ├── mail/                 # SMTP email client
│   ├── router/               # Gin setup + CORS + auth middleware
│   ├── testutils/            # Test environment helpers
│   ├── user/                 # Auth, JWT, user CRUD, password reset
│   ├── appsystem/            # Version + health endpoints
│   └── items/                # Example generic CRUD module
├── frontend/
│   ├── src/
│   │   ├── main.js           # App bootstrap (Pinia, Router, i18n)
│   │   ├── App.vue           # Root component
│   │   ├── router/           # Vue Router with auth guards
│   │   ├── stores/           # Pinia stores (userStore, languageStore)
│   │   ├── utils/            # api.js, auth.js, dateUtils.js
│   │   ├── locales/          # DE + EN translations (plain JS)
│   │   ├── components/       # Menu, Login/Register forms
│   │   ├── views/            # Page-level view components
│   │   └── assets/           # main.css + base.css (design system)
│   └── nginx.conf            # SPA routing for production
└── docker/
    ├── Dockerfile.backend
    ├── Dockerfile.backend.dev
    ├── Dockerfile.frontend
    ├── Dockerfile.frontend.dev
    ├── docker-compose.yml        # Production
    └── docker-compose.dev.yml    # Development

How to Use This Template

1. Copy and rename the project

cp -r template/ my-project/
cd my-project/

2. Update the Go module name

Replace myapp with your module name in all Go files:

# Update go.mod
sed -i 's|myapp|github.com/yourorg/yourproject|g' backend/go.mod

# Update all imports
find backend/ -name "*.go" -exec sed -i 's|myapp|github.com/yourorg/yourproject|g' {} \;

3. Configure environment variables

Copy and edit the environment files:

cp backend/.env.example backend/.env
# Edit backend/.env with your database credentials, JWT secret, SMTP config

# For frontend:
# Edit frontend/.env or set VITE_API_URL in docker-compose

Key variables in backend/.env:

SERVER_PORT=8180
DATABASE_TYPE=mysql
DATABASE_URL=user:password@tcp(localhost:3306)/myapp?charset=utf8mb4&parseTime=True&loc=Local
JWT_SECRET=your_secure_random_secret_here
FRONTEND_URL=http://localhost:5173
SMTP_HOST=smtp.example.com
SMTP_PORT=465
SMTP_USER=user@example.com
SMTP_PASSWORD=yourpassword
SMTP_FROM=noreply@example.com

4. Start development environment

cd docker/
docker-compose -f docker-compose.dev.yml up -d

Services:

• Backend API: http://localhost:8180
• Frontend: http://localhost:5173
• MariaDB: localhost:3306
• phpMyAdmin: http://localhost:8082

5. Start production environment

cd docker/
docker-compose up -d

---

Adding a New Domain Module

Backend Module Pattern

Create a new directory, e.g. backend/products/:

products/
  model.go       # GORM struct + MigrateStructure()
  handlers.go    # Gin handlers
  routes.go      # RegisterRoutes(r *gin.RouterGroup)
  *_test.go      # Tests with setupTestEnvironment(t)

Register in cmd/main.go:

import "myapp/products"

// In main() after ConnectDatabase():
products.MigrateStructure(database.DB)

// After router setup:
products.RegisterRoutes(protected)

Frontend Module Pattern

1. Add routes to src/router/index.js
2. Create views in src/views/
3. Add i18n keys to both src/locales/de and src/locales/en
4. Add menu items to src/components/Menu.vue

---

API Endpoints (Built-in)

Public (no auth)

Method	Path	Description
POST	/register	Register new user
POST	/login	Login, returns JWT token
POST	/password-reset/request	Request password reset email
POST	/password-reset/validate	Validate reset token
POST	/password-reset/reset	Set new password
GET	/api/public/version	Frontend version info
GET	/api/public/systeminfo	System info

Protected (requires Authorization: Bearer <token>)

Method	Path	Description
GET	/api/user/profile	Get current user profile
PUT	/api/user/display-name	Update display name
PUT	/api/user/email	Update email
PUT	/api/user/password	Change password
PUT	/api/user/language	Set preferred language
GET	/api/items	List current user's items
POST	/api/items	Create item
GET	/api/items/:id	Get item
PUT	/api/items/:id	Update item
DELETE	/api/items/:id	Delete item

Admin only (role = admin)

Method	Path	Description
GET	/api/users	List all users
GET	/api/users/:id	Get user
PUT	/api/users/:id/role	Change user role
PUT	/api/users/:id/password	Change user password
DELETE	/api/users/:id	Delete user

---

Running Tests

cd backend/
go test ./...

# Run specific module tests
go test -v ./items/
go test -v ./user/

Tests use an in-memory SQLite database. No external services required.

---

User Roles

Role	Description
standard	Default role for registered users
maintainer	Elevated privileges (define in your domain logic)
admin	Full access including user management

---

Customization Checklist

• Replace myapp module name throughout backend
• Update frontend/package.json name field
• Set strong JWT_SECRET in production
• Configure SMTP for password reset emails
• Update FRONTEND_URL in docker-compose for CORS
• Replace placeholder text in HelpView.vue and locales
• Update i18n keys in src/locales/de and src/locales/en
• Replace items module with your domain models
• Update Menu.vue with your application's navigation
• Customize LandingView.vue for your application
• Set production domain in docker-compose.yml