# App Directory Agent Instructions

## Overview

The `app/` directory contains the main application logic following a clean layered architecture. Each layer has specific responsibilities and patterns.

## Layer Dependencies

```
controllers → models → repo → entity
     ↓          ↓
  workflow   worker
```

**Key rules:**
- Controllers ONLY call models (never repos directly)
- Models call repos and other models
- Repos ONLY interact with database via GORM
- Workflows/workers call models for business logic

## Package Structure

| Package | Purpose | Pattern Reference |
|---------|---------|-------------------|
| `container/` | DI container with `container.Global()` | Singleton, dig |
| `controllers/` | gRPC/HTTP entry points | See `controllers/AGENTS.md` |
| `models/` | Core business logic | See `models/AGENTS.md` |
| `repo/` | Data persistence layer | See `repo/AGENTS.md` |
| `workflow/` | Async DAG workflows | See `workflow/AGENTS.md` |
| `worker/` | Scheduled background jobs | gocron |
| `internal/` | Shared utilities | Feature gates, facades |
| `config/` | Error codes, constants | - |

## Dependency Injection

All dependencies are wired in `container/container.go`:

```go
// Access global container
c := container.Global()

// Use dependencies
backup, err := c.BackupRepo.Load(ctx, id)
err = c.SnapshotBackupModel.Create(ctx, req)
```

**Adding new components:**
1. Define interface in appropriate layer
2. Create implementation
3. Add to `GlobalContainer` struct
4. Wire in `SetUpContainers()` function

## Cross-Cutting Concerns

### Context Propagation
```go
// Always pass context for tracing/cancellation
func (m *impl) DoSomething(ctx context.Context, ...) error {
    ctx = log.WithTraceID(ctx)
    logger := log.GetLogger(ctx)
    // ...
}
```

### Error Handling
```go
// Use bizerr for all business errors
return bizerr.New(errcode.SomeError, "descriptive message %d", id)

// Chain errors for context
return err.Chain("doing something for %d", id)
```

## Testing Utilities

- `repo.GetFakeDB()` - In-memory MySQL for integration tests
- `mock.NewXxx(t)` - Generated mocks via mockery
- `testify/suite` - Suite-based test organization

## Common Import Patterns

```go
import (
    // Models
    backup "github.com/tidbcloud/dataflow-service/app/models/backup"
    backup_impl "github.com/tidbcloud/dataflow-service/app/models/backup/impl"
    
    // Repos  
    backup_repo "github.com/tidbcloud/dataflow-service/app/repo/backup"
    
    // Entity
    "github.com/tidbcloud/dataflow-service/app/repo/entity"
    
    // Domain types
    "github.com/tidbcloud/dataflow-service/app/models/domain"
    
    // Utilities
    "github.com/tidbcloud/dataflow-service/pkg/log"
    bizerr_wrapper "github.com/tidbcloud/dataflow-service/pkg/bizerr-wrapper"
)
```