documentation-docusaurus/references/go-monorepo-conventions.md

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)

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