feat: merge Docusaurus and Gitea documentation skills

2026-08-14 12:32:08 +00:00
parent cfb006d7ea
commit b08614dc90
28 changed files with 4202 additions and 1 deletions
@@ -0,0 +1,86 @@
+# 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