# 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

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

### 2. Update the Go module name

Replace `myapp` with your module name in all Go files:

```bash
# 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:

```bash
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`:
```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

```bash
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

```bash
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`:
```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

```bash
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`