87 lines
2.7 KiB
Markdown
87 lines
2.7 KiB
Markdown
# 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
|