Add project documentation and linter config

.golangci.yml

@@ -0,0 +1,117 @@
+version: "2"
+
+run:
+  go: "1.24"
+  tests: false
+
+linters:
+  enable:
+    # Additional linters requested
+    - testifylint      # Checks usage of github.com/stretchr/testify
+    - usetesting       # usetesting is an analyzer that detects using os.Setenv instead of t.Setenv since Go 1.17
+    # - tagliatelle      # Disabled: we need snake_case for external API compatibility
+    - nlreturn         # nlreturn checks for a new line before return and branch statements
+    - nilnil           # Checks that there is no simultaneous return of nil error and an invalid value
+    - nestif           # Reports deeply nested if statements
+    - mnd              # An analyzer to detect magic numbers
+    - lll              # Reports long lines
+    - intrange         # intrange is a linter to find places where for loops could make use of an integer range
+    - gochecknoglobals # Check that no global variables exist
+
+    # Default/existing linters that are commonly useful
+    - govet
+    - errcheck
+    - staticcheck
+    - unused
+    - ineffassign
+    - misspell
+    - revive
+    - gosec
+    - unconvert
+    - unparam
+
+linters-settings:
+  lll:
+    line-length: 120
+
+  nestif:
+    min-complexity: 4
+
+  nlreturn:
+    block-size: 2
+
+  revive:
+    rules:
+      - name: var-naming
+        arguments:
+          - []
+          - []
+          - "upperCaseConst=true"
+
+  tagliatelle:
+    case:
+      rules:
+        json: snake
+        yaml: snake
+        xml: snake
+        bson: snake
+
+  testifylint:
+    enable-all: true
+
+  usetesting: {}
+
+issues:
+  max-issues-per-linter: 0
+  max-same-issues: 0
+  exclude-rules:
+    # Exclude unused parameter warnings for cobra command signatures
+    - text: "parameter '(args|cmd)' seems to be unused"
+      linters:
+        - revive
+
+    # Allow ALL_CAPS constant names
+    - text: "don't use ALL_CAPS in Go names"
+      linters:
+        - revive
+
+    # Allow snake_case JSON tags for external API compatibility
+    - path: "internal/types/ris.go"
+      linters:
+        - tagliatelle
+
+    # Allow snake_case JSON tags for database models
+    - path: "internal/database/models.go"
+      linters:
+        - tagliatelle
+
+    # Allow generic package name for types that define data structures
+    - path: "internal/types/"
+      text: "avoid meaningless package names"
+      linters:
+        - revive
+
+    # Allow globals in the globals package (by design)
+    - path: "internal/globals/"
+      linters:
+        - gochecknoglobals
+
+    # Allow globals in main (Version/Buildarch set by ldflags)
+    - path: "cmd/"
+      linters:
+        - gochecknoglobals
+
+    # Allow blank imports for driver registration
+    - text: "blank-imports"
+      linters:
+        - revive
+
+    # Allow unused fx.Lifecycle parameters (required by fx signature)
+    - text: "parameter 'lc' seems to be unused"
+      linters:
+        - revive
+
+    # Allow unused context parameters in fx hooks
+    - text: "parameter 'ctx' seems to be unused"
+      linters:
+        - revive