# Go Monorepo Conventions — SKIC Playground

## Directory Layout

```
skic-v1-playground/
├── documentation/              # Docusaurus site
├── stock-market-pro/           # Go service
│   ├── cmd/server/main.go
│   ├── internal/               # App-private packages
│   │   ├── ingestor/
│   │   ├── analysis/
│   │   ├── signals/
│   │   └── notifier/
│   ├── pkg/                    # Public packages (if any)
│   ├── Dockerfile
│   ├── Makefile
│   └── go.mod
├── shared/                     # Cross-app Go libraries
│   ├── discord/
│   ├── config/
│   └── telemetry/
├── infra/
│   └── docker-compose.yml
├── go.work                     # Go workspace — ties all modules together
└── Makefile                    # Root targets: build all, test all
```

## go.work File

```
go 1.22

use (
    ./stock-market-pro
    ./shared/discord
    ./shared/config
    ./shared/telemetry
)
```

Local modules reference each other without `replace` directives.

## Standard Go Libraries (SKIC stack)

| Package | Purpose |
|---|---|
| `net/http` | HTTP server/client |
| `encoding/json` | JSON |
| `database/sql` + `modernc.org/sqlite` | SQLite (dev) |
| `github.com/lib/pq` | PostgreSQL/TimescaleDB (prod) |
| `github.com/rs/zerolog` | Structured logging |
| `github.com/spf13/viper` | Config from env vars |
| `github.com/robfig/cron/v3` | Scheduled jobs |
| `golang.org/x/sync` | Concurrency utilities |

## Code Conventions

- **Error wrapping**: `fmt.Errorf("context: %w", err)` — never swallow errors
- **Logging**: zerolog structured JSON, no `fmt.Println` in prod
- **Tests**: table-driven, `testify/assert`, race detector on CI (`-race`)
- **Config**: env vars via Viper, validated at startup with explicit error

## Python as Sidecar

Python (pandas-ta, ta-lib, scikit-learn) runs as a **sidecar HTTP/gRPC service** when the Go ecosystem is thin for data/ML. The Go service calls localhost endpoints.

## Makefile Targets (per app)

```makefile
build:   go build -o bin/server ./cmd/server
test:    go test ./... -race -cover
lint:    golangci-lint run
docker:  docker build -t $(APP_NAME):$(VERSION) .
run:     source .env && go run ./cmd/server
```

## Adding a New App

1. `mkdir skic-v1-playground/<app-name>/`
2. `go mod init gitea.lego-cloud.eu/skic-v1-playground/<app-name>`
3. Add `use ./<app-name>` to `go.work`
4. Copy `.gitea/workflows/build.yml` from template
5. Create multi-stage Dockerfile: `golang:1.22-alpine` → `alpine:3.19`
6. Add docs under `documentation/docs/products/<app-name>/` with C4 structure
7. Add to `documentation/src/pages/index.tsx` applications array