Develop

.env.example

@@ -0,0 +1,41 @@
+APP_NAME=library
+APP_VERSION=0.1.0
+APP_ENV=development
+
+# Application Port
+# For local development (make run-api): the port your app listens on
+# For Docker (make docker-up): container always listens on 8080 (hardcoded in docker-compose.yml)
+PORT=8080
+
+# Docker Host Port (optional, only used by docker-compose)
+# Maps host port to container port 8080
+# HOST_PORT=8080
+
+DATABASE_URL=postgres://library:secret@localhost:5432/library?sslmode=disable
+POSTGRES_USER=library
+POSTGRES_PASSWORD=secret
+POSTGRES_DB=library
+
+# ⚠️ For local development (make run-api): use localhost:6380
+# ⚠️ For Docker (make docker-up): IGNORED - hardcoded to redis://redis:6379 in docker-compose.yml
+REDIS_URL=redis://localhost:6380
+
+JWT_SECRET=secret
+ACCESS_TOKEN_EXPIRY=30
+REFRESH_TOKEN_EXPIRY=720
+
+GOOGLE_CLIENT_ID=xxx
+GOOGLE_CLIENT_SECRET=xxx
+GOOGLE_REDIRECT_URL=http://localhost:8080/api/v1/portal/auth/google/callback
+
+OTP_EXPIRY=1
+
+# Elasticsearch Configuration
+# ⚠️ For local development (make run-api): use localhost:9200
+# ⚠️ For Docker (make docker-up): IGNORED - hardcoded to http://elasticsearch:9200 in docker-compose.yml
+ELASTICSEARCH_URL=http://localhost:9200
+
+REQUEST_TIMEOUT=30s
+ALLOWED_ORIGINS=http://localhost:3000,http://localhost:5173
+RATE_LIMIT_REQUESTS=100 
+RATE_LIMIT_WINDOW=1m

.github/workflows/ci.yml

@@ -0,0 +1,113 @@
+name: CI
+
+on:
+  push:
+    branches: [master, develop]
+  pull_request:
+    branches: [master, develop]
+
+jobs:
+
+  lint:
+    name: Lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.26'
+          cache: true
+
+      - name: golangci-lint
+        uses: golangci/golangci-lint-action@v8
+        with:
+          version: latest
+          args: --timeout=5m
+
+  test-unit:
+    name: Unit Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.26'
+          cache: true
+
+      - name: Download modules
+        run: go mod download
+
+      - name: Run unit tests
+        run: go test ./internal/... -v -race -count=1 -coverprofile=coverage.out
+
+      - name: Upload coverage
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage
+          path: coverage.out
+
+  test-integration:
+    name: Integration Tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.26'
+          cache: true
+
+      - name: Download modules
+        run: go mod download
+
+      - name: Run integration tests
+        run: go test ./tests/integration/... -v -race -count=1 -timeout 120s
+        env:
+          TESTCONTAINERS_RYUK_DISABLED: true
+
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    needs: [lint, test-unit, test-integration]
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.26'
+          cache: true
+
+      - name: Build all binaries
+        run: make build
+
+      - name: Upload binaries
+        uses: actions/upload-artifact@v4
+        with:
+          name: binaries
+          path: bin/
+
+  docker:
+    name: Docker Build
+    runs-on: ubuntu-latest
+    needs: build
+    if: github.ref == 'refs/heads/master'
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build Docker image
+        run: docker build -t librecore:${{ github.sha }} .
+
+      - name: Smoke test image
+        run: |
+          docker run --rm -d \
+            -e APP_ENV=production \
+            -e DATABASE_URL=postgres://x:x@localhost/x \
+            -e REDIS_URL=redis://localhost:6379 \
+            -e JWT_SECRET=ci-test-secret \
+            -p 8080:8080 \
+            --name librecore_smoke \
+            librecore:${{ github.sha }} || true
+          sleep 3
+          docker stop librecore_smoke || true

.gitignore

@@ -7,6 +7,7 @@
 *.dll
 *.so
 *.dylib
+bin/
 
 # Test binary, built with `go test -c`
 *.test
@@ -28,5 +29,5 @@ go.work.sum
 .env
 
 # Editor/IDE
-# .idea/
-# .vscode/
+.idea/
+.vscode/

.golangci.yml

@@ -0,0 +1,50 @@
+version: "2"
+run:
+  timeout: 5m
+  go: '1.26'
+
+linters:
+  enable:
+    - errcheck
+    - govet
+    - ineffassign
+    - staticcheck
+    - unused
+    - misspell
+    - revive
+    - exhaustive
+    - noctx
+    - bodyclose
+  settings:
+    revive:
+      rules:
+        - name: exported
+          disabled: true
+        - name: package-comments
+          disabled: true
+        - name: redefines-builtin-id
+          severity: warning
+        - name: unexported-return
+          severity: warning
+        - name: blank-imports
+          severity: warning
+    exhaustive:
+      default-signifies-exhaustive: true
+  exclusions:
+    rules:
+      - path: _test\.go
+        linters: [errcheck, noctx]
+      - path: tests/
+        linters: [errcheck, noctx, revive]
+      - path: docs/
+        linters: [all]
+      - path: pkg/i18n/fa\.go
+        linters: [staticcheck]
+
+formatters:
+  enable:
+    - gofmt
+
+issues:
+  max-issues-per-linter: 0
+  max-same-issues: 0

CONTRIBUTING.md

@@ -0,0 +1,106 @@
+# Contributing to LibreCore
+
+Thank you for considering contributing. This document covers everything
+you need to get started.
+
+---
+
+## Development Setup
+
+### Prerequisites
+- Go 1.23+
+- Docker + Docker Compose
+- `golangci-lint` — `go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest`
+- `swag` — `go install github.com/swaggo/swag/cmd/swag@latest`
+
+### First-time setup
+```bash
+git clone https://github.com/mohammad-farrokhnia/library.git
+cd library
+cp .env.example .env
+make docker-up
+make migrate
+make seed EMAIL=admin@library.com PASSWORD=secret MOBILE=09120000000 NATIONAL_CODE=1234567890
+make run-api
+```
+
+---
+
+## Git Flow
+
+We follow trunk-based development with short-lived feature branches.
+
+```
+main         ← production, protected, requires PR + review
+develop      ← integration branch, PRs target this
+feature/*    ← one branch per feature
+hotfix/*     ← emergency production fixes
+release/*    ← release stabilization
+```
+
+---
+
+## Branch Naming
+
+| Type | Pattern | Example |
+|---|---|---|
+| Feature | `feature/short-description` | `feature/book-recommendations` |
+| Bug fix | `fix/what-was-broken` | `fix/borrow-transaction-race` |
+| Hotfix | `hotfix/critical-issue` | `hotfix/jwt-validation` |
+| Chore | `chore/what-changed` | `chore/update-go-1.24` |
+
+---
+
+## Commit Convention
+
+We use [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+type(scope): short description
+
+feat(books): add copy management endpoints
+fix(auth): prevent session reuse after logout
+docs(readme): update installation steps
+test(borrow): add limit enforcement integration test
+chore(deps): update golang-jwt to v5.2.1
+refactor(cache): extract GetOrSet into generic helper
+```
+
+Types: `feat` `fix` `docs` `test` `chore` `refactor` `perf` `ci`
+
+---
+
+## Pull Request Process
+
+1. Fork the repo and create your branch from `develop`
+2. Write tests for any new behaviour
+3. Ensure `make lint` and `make test` pass
+4. Update Swagger docs if you changed any handler: `make swagger`
+5. Open a PR targeting `develop` with a clear description
+
+---
+
+## Code Standards
+
+- All repository methods must accept `context.Context` as the first parameter
+- All errors must be `AppError` from `pkg/errors` — never raw `errors.New`
+- Business rules belong in `service/`, never in `handler/` or `repository/`
+- New i18n message codes must be added to all locale files (`en.go`, `fa.go`)
+- Every new endpoint needs a Swagger annotation
+
+---
+
+## Running Tests
+
+```bash
+make test-unit          # fast, no Docker
+make test-integration   # requires Docker
+make test-coverage      # generates coverage.html
+```
+
+---
+
+## Project Structure
+
+See the [architecture document](docs/architecture.md) for the full layered
+architecture diagram and design decisions.

Dockerfile

@@ -0,0 +1,30 @@
+FROM golang:1.25-alpine AS builder
+
+WORKDIR /app
+
+RUN apk add --no-cache git
+
+COPY go.mod go.sum ./
+
+RUN go mod download
+
+COPY . .
+
+ARG VERSION=dev
+RUN CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo \
+    -ldflags "-s -w -X main.Version=${VERSION}" \
+    -o main ./cmd/api
+
+FROM alpine:latest
+
+RUN apk --no-cache add ca-certificates
+
+WORKDIR /root/
+
+COPY --from=builder /app/main .
+
+COPY --from=builder /app/migrations ./migrations
+
+EXPOSE 8080
+
+CMD ["./main"]