@johnnyboy11234/esg-idea-contest 0.0.0-stage → 0.1.0

package/AGENTS.md

@@ -0,0 +1,171 @@
+# Agent Instructions
+
+Project: **ESG Idea Contest** registration system. Employees register, form teams of 1–4 and submit one Idea (one slide file per team); admins manage everything; every write is audited. The repo currently holds **documents only** — no `backend/` or `frontend/` code exists yet (first code PR is `B0-01` in `docs/PR-plan.md`).
+
+## Where things are (read in this order)
+
+| Need | File |
+|---|---|
+| What to build (requirements, permission matrix, NFRs) | `docs/PRD.md` — **wins over every other document on behaviour** |
+| System design, principles, decision log (D1–D61) | `docs/Architecture/Architecture.md` |
+| Backend design (Go): modules, pipeline, transactions, session/CSRF, audit, data model, tests | `docs/Architecture/Backend.md` |
+| Frontend design | `docs/Architecture/Frontend.md` |
+| Sequence diagrams (create / replace / delete / download, storage consistency) | `docs/Architecture/Sequence.md` |
+| API contract (endpoints, error codes, response bodies) | `docs/API/` (start at `README.md`) |
+| Why Go, and the sqlc findings | `docs/Adr/0001-Backend-in-go.md`, `docs/Adr/0001-Annex-sqlc-spike.md` |
+| Unresolved questions (OI-nn) and owner confirmations | `docs/Open-items.md` — the only tracker for them |
+| PR breakdown, slices S0–S7, PR rules and Definition of Done | `docs/PR-plan.md` (plan only; work items live in `bd`) |
+
+Not written yet (do not cite as existing): `docs/modules/`, `docs/runbook.md`, `docs/test-report.md`, `docs/limitations.md`, root `README.md`, `backend/api/openapi.yaml`.
+
+If documents disagree: PRD > ADR > Backend/Frontend > Architecture decision log; report the conflict, do not silently pick one. Status markers: **[Decided]** / **[Proposed]** / **[Open]** (open items in `docs/Open-items.md`). Do not treat **[Proposed]** as agreed.
+
+## Stack (decided)
+
+Go 1.26 · chi · spec-first OpenAPI (oapi-codegen, standard non-strict server) · sqlc + `go-sql-driver/mysql` against MariaDB · Flyway migrations · own session/CSRF/throttling middleware · `log/slog` · minio-go (`MaxRetries: 1`) · React + Vite + TypeScript frontend. Java/Spring text in older decision-log rows is superseded.
+
+## Build & Test (target commands; they start to work when the code PRs land)
+
+```bash
+golangci-lint run
+go test -race ./...                       # unit
+go test -race -tags integration ./...     # needs Docker (testcontainers-go, real MariaDB + migrations)
+go test -coverpkg=./... -coverprofile=cover.out ./... && go tool cover -func=cover.out   # gate: statement coverage >= 80 %
+sqlc generate && go generate ./...        # must produce no diff
+```
+
+## Conventions that are easy to get wrong
+
+- Packages by feature: `internal/<module>/` with implementation in `internal/<module>/internal/`; dependency direction is checked by an import-graph test and `depguard`. No ORM.
+- Uniform 404: a resource the caller may not see answers the **same uniform 404** as a missing one (and is audited as DENIED). Do not add distinguishing responses.
+- Database time is the only clock. A write succeeds only together with its audit row (track A inside the tx; track B `RecordRejected` in its own tx).
+- Check order: 413 → 401 → CSRF 403 → 404 / role / state, all **before** the multipart body is read. JSON bodies: pointer fields, unknown fields ignored, duplicate keys and wrong types → 400.
+- Unknown transaction outcome (`COMMIT` error not in SQLState class 23/40): keep storage objects; cleanup goes through `pending_file_deletion`.
+- Every PR that adds an error code updates the catalogue, `testdata/error-codes.json`, `docs/API/error-codes.md` and the zh-TW/en dictionaries; every touched permission-matrix cell gets a test.
+- Repo documents are English. No secrets, Vault paths or internal hostnames in `site/`.
+
+This project uses **bd** (beads) for issue tracking. Run `bd prime` for full workflow context.
+
+> **Architecture in one line:** Issues live in a local Dolt database
+> (`.beads/dolt/`); cross-machine sync uses `bd dolt push/pull` (a
+> git-compatible protocol), stored under `refs/dolt/data` on your git
+> remote — separate from `refs/heads/*` where your code lives.
+> `.beads/issues.jsonl` is a passive export, not the wire protocol.
+>
+> See [sync-concepts](https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md)
+> for the one-screen overview and anti-patterns (don't treat JSONL as the
+> source of truth; don't `bd import` during normal operation; don't
+> reach for third-party Dolt hosting before trying the default).
+
+## Quick Reference
+
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --claim  # Claim work atomically
+bd close <id>         # Complete work
+bd dolt push          # Push beads data to remote
+```
+
+## Non-Interactive Shell Commands
+
+**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts.
+
+Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.
+
+**Use these forms instead:**
+```bash
+# Force overwrite without prompting
+cp -f source dest           # NOT: cp source dest
+mv -f source dest           # NOT: mv source dest
+rm -f file                  # NOT: rm file
+
+# For recursive operations
+rm -rf directory            # NOT: rm -r directory
+cp -rf source dest          # NOT: cp -r source dest
+```
+
+**Other commands that may prompt:**
+- `scp` - use `-o BatchMode=yes` for non-interactive
+- `ssh` - use `-o BatchMode=yes` to fail instead of prompting
+- `apt-get` - use `-y` flag
+- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var
+
+<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:1105d646 -->
+## Beads Issue Tracker
+
+This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
+
+### Quick Reference
+
+```bash
+bd ready              # Find available work
+bd show <id>          # View issue details
+bd update <id> --claim  # Claim work
+bd close <id>         # Complete work
+```
+
+### Rules
+
+- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
+- Run `bd prime` for detailed command reference and session close protocol
+- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files
+
+**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns.
+
+## Agent Context Profiles
+
+The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.
+
+- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands.
+- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise.
+- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.
+
+## Session Completion
+
+This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.
+
+1. **File issues for remaining work** - Create beads for anything that needs follow-up
+2. **Run quality gates** (if code changed) - Tests, linters, builds
+3. **Update issue status** - Close finished work, update in-progress items
+4. **Handle git/sync by active profile**:
+   ```bash
+   # Conservative/minimal/default: report status and proposed commands; wait for approval.
+   git status
+
+   # Team-maintainer opt-in only, unless current instructions forbid it:
+   git pull --rebase
+   git push
+   git status
+   ```
+5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step
+
+**Critical rules:**
+- Explicit user or orchestrator instructions override this Beads block.
+- Do not commit or push without clear authority from the active profile or the current user request.
+- If a required sync or push is blocked, stop and report the exact command and error.
+<!-- END BEADS INTEGRATION -->
+
+<!-- BEGIN BEADS CODEX SETUP: generated by bd setup codex -->
+## Beads Issue Tracker
+
+Use Beads (`bd`) for durable task tracking in repositories that include it. Use the `beads` skill at `.agents/skills/beads/SKILL.md` (project install) or `~/.agents/skills/beads/SKILL.md` (global install) for Beads workflow guidance, then use the `bd` CLI for issue operations.
+
+### Quick Reference
+
+```bash
+bd ready                # Find available work
+bd show <id>            # View issue details
+bd update <id> --claim  # Claim work
+bd close <id>           # Complete work
+bd prime                # Refresh Beads context
+```
+
+### Rules
+
+- Use `bd` for all task tracking; do not create markdown TODO lists.
+- Run `bd prime` when Beads context is missing or stale. Codex 0.129.0+ can load Beads context automatically through native hooks; use `/hooks` to inspect or toggle them.
+- Keep persistent project memory in Beads via `bd remember`; do not create ad hoc memory files.
+
+**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md for details and anti-patterns.
+<!-- END BEADS CODEX SETUP -->

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Johnson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Makefile

@@ -0,0 +1,20 @@
+# Repo-level developer entry points. Backend targets live in backend/Makefile.
+COMPOSE ?= docker compose
+
+.PHONY: dev-up dev-down dev-reset migrate
+
+## Start MariaDB and MinIO in the background (waits for MariaDB to be healthy).
+dev-up:
+	$(COMPOSE) up -d --wait mariadb minio
+
+## Stop the stack, keep data volumes.
+dev-down:
+	$(COMPOSE) down
+
+## Stop the stack and delete all local data.
+dev-reset:
+	$(COMPOSE) down -v
+
+## Apply Flyway migrations from backend/db/migration (idempotent).
+migrate:
+	$(COMPOSE) run --rm flyway

package/backend/.dockerignore

@@ -0,0 +1,4 @@
+bin
+cover.out*
+**/*_test.go
+test

package/backend/.golangci.yml

@@ -0,0 +1,33 @@
+version: "2"
+run:
+  build-tags: [integration]
+linters:
+  default: none
+  enable:
+    - errcheck
+    - govet
+    - staticcheck
+    - ineffassign
+    - unused
+    - gosec
+    - errorlint
+    - depguard
+  settings:
+    depguard:
+      rules:
+        no-orm:
+          list-mode: lax
+          files: ["$all"]
+          deny:
+            - pkg: gorm.io
+              desc: ORMs are banned (Backend.md §2.3); use sqlc
+            - pkg: entgo.io
+              desc: ORMs are banned (Backend.md §2.3); use sqlc
+            - pkg: github.com/uptrace/bun
+              desc: ORMs are banned (Backend.md §2.3); use sqlc
+  exclusions:
+    rules:
+      - path: _test\.go
+        linters: [gosec, errcheck]
+formatters:
+  enable: [gofmt]

package/backend/Dockerfile

@@ -0,0 +1,19 @@
+# Backend image (B0-04 / O0-06). Build context is backend/:
+#   docker build -t esg-backend backend
+FROM golang:1.26 AS build
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN CGO_ENABLED=0 go build -trimpath -ldflags="-s -w" -o /out/server ./cmd/server
+
+# Static binary on distroless: no shell, uid 65532, works with a read-only root
+# filesystem (upload spooling needs a /tmp emptyDir, mounted by the chart).
+FROM gcr.io/distroless/static-debian12:nonroot
+COPY --from=build /out/server /server
+# About 75 % of the container memory limit; the chart overrides it together
+# with the limit (Backend.md §12).
+ENV GOMEMLIMIT=384MiB
+EXPOSE 8080 8081
+USER 65532:65532
+ENTRYPOINT ["/server"]

package/backend/Makefile

@@ -0,0 +1,39 @@
+# Backend developer entry points. `make ci` is what the GitHub Actions workflow runs (.github/workflows/ci.yml).
+GO ?= go
+COVER_MIN ?= 80
+
+.PHONY: build lint test test-integration cover ci run generate generate-check spec-lint
+
+build:
+	CGO_ENABLED=0 $(GO) build -o bin/server ./cmd/server
+
+lint:
+	golangci-lint run
+
+test:
+	$(GO) test -race ./...
+
+test-integration:
+	$(GO) test -race -tags integration ./...
+
+# One run: unit + integration (needs Docker), -race, a single merged profile.
+cover:
+	$(GO) test -race -tags integration -coverpkg=./... -coverprofile=cover.out ./...
+	@# ADR-0001 O2 (recommended, awaiting confirmation): generated code is outside the coverage denominator.
+	@grep -v '\.gen\.go:' cover.out > cover.out.tmp && mv -f cover.out.tmp cover.out
+	@$(GO) tool cover -func=cover.out | awk -v min=$(COVER_MIN) '/^total:/ { sub("%","",$$3); print "total coverage " $$3 "%"; if ($$3+0 < min) { print "below " min "%"; exit 1 } }'
+
+generate:
+	$(GO) generate ./...
+
+# Generated code is committed; fail when it is stale (B0-12 acceptance: `go generate` no diff).
+generate-check: generate
+	@git diff --exit-code -- internal/api || { echo "generated code is stale: run make generate"; exit 1; }
+
+spec-lint:
+	cd api && npx --yes @stoplight/spectral-cli@6.15.0 lint openapi.yaml --ruleset .spectral.yaml --fail-severity=warn
+
+ci: lint generate-check spec-lint cover
+
+run:
+	$(GO) run ./cmd/server

package/backend/api/.spectral.yaml

@@ -0,0 +1,31 @@
+extends: ["spectral:oas"]
+rules:
+  info-contact: off
+  operation-description: off
+  # Backend.md §11: every write declares X-CSRF-Token (checked by the CSRF middleware).
+  write-declares-csrf-header:
+    description: POST/PUT/DELETE operations must reference the X-CSRF-Token parameter.
+    severity: error
+    given: "$.paths[*][?(@property === 'post' || @property === 'put' || @property === 'delete')]"
+    then:
+      field: parameters
+      function: schema
+      functionOptions:
+        schema:
+          type: array
+          contains:
+            type: object
+            required: [name, in]
+            properties:
+              name: { const: X-CSRF-Token }
+              in: { const: header }
+  # Errors are RFC 9457 problem+json, never another media type.
+  errors-are-problem-json:
+    description: 4xx/5xx responses must use application/problem+json.
+    severity: error
+    given: "$.paths[*][*].responses[?(@property.match(/^[45]/))]"
+    then:
+      field: "$ref"
+      function: enumeration
+      functionOptions:
+        values: ["#/components/responses/Problem"]

package/backend/api/oapi-codegen.yaml

@@ -0,0 +1,8 @@
+# Standard (non-strict) chi server, Backend.md A1. Output is committed; CI fails on a diff.
+package: api
+output: api.gen.go
+generate:
+  models: true
+  chi-server: true
+output-options:
+  skip-prune: true

package/backend/api/openapi.yaml

@@ -0,0 +1,228 @@
+openapi: 3.0.3
+info:
+  title: ESG Idea Contest API
+  version: 1.0.0
+  description: >
+    Single source of the API contract (Backend.md G4). Skeleton: shared components plus the
+    operations needed to lock binding rules; the remaining endpoints of docs/API/api-endpoints.md
+    are added by their own PRs. Error codes: docs/API/error-codes.md, testdata/error-codes.json.
+servers:
+  - url: /api/v1
+security:
+  - sessionCookie: []
+tags:
+  - name: auth
+  - name: deadline
+  - name: ideas
+paths:
+  /auth/csrf:
+    get:
+      operationId: getCsrfToken
+      tags: [auth]
+      summary: Session-bound CSRF token (anonymous before login)
+      security: []
+      responses:
+        '200':
+          description: Token to send as X-CSRF-Token on every write
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/CsrfTokenResponse' }
+        '429': { $ref: '#/components/responses/Problem' }
+        '500': { $ref: '#/components/responses/Problem' }
+  /auth/logout:
+    post:
+      operationId: logout
+      tags: [auth]
+      summary: End the session
+      security: []
+      parameters:
+        - $ref: '#/components/parameters/CsrfToken'
+      responses:
+        '204': { description: Logged out }
+        '403': { $ref: '#/components/responses/Problem' }
+        '500': { $ref: '#/components/responses/Problem' }
+  /deadline:
+    get:
+      operationId: getDeadline
+      tags: [deadline]
+      summary: Submission deadline, state and database server time
+      security: []
+      responses:
+        '200':
+          description: Current deadline state
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/Deadline' }
+        '500': { $ref: '#/components/responses/Problem' }
+        '503': { $ref: '#/components/responses/Problem' }
+  /ideas:
+    get:
+      operationId: listIdeas
+      tags: [ideas]
+      summary: List Ideas visible to the caller
+      parameters:
+        - name: page
+          in: query
+          schema: { type: integer, minimum: 1, default: 1 }
+        - name: size
+          in: query
+          schema: { type: integer, minimum: 1, maximum: 100, default: 20 }
+      responses:
+        '200':
+          description: One page of IdeaSummary
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/IdeaPage' }
+        '401': { $ref: '#/components/responses/Problem' }
+        '422': { $ref: '#/components/responses/Problem' }
+        '500': { $ref: '#/components/responses/Problem' }
+  /ideas/{id}:
+    get:
+      operationId: getIdea
+      tags: [ideas]
+      summary: Idea detail
+      parameters:
+        - $ref: '#/components/parameters/IdeaId'
+      responses:
+        '200':
+          description: IdeaDetail
+          content:
+            application/json:
+              schema: { $ref: '#/components/schemas/IdeaDetail' }
+        '401': { $ref: '#/components/responses/Problem' }
+        '404': { $ref: '#/components/responses/Problem' }
+        '500': { $ref: '#/components/responses/Problem' }
+components:
+  securitySchemes:
+    sessionCookie:
+      type: apiKey
+      in: cookie
+      name: __Host-session
+  parameters:
+    CsrfToken:
+      name: X-CSRF-Token
+      in: header
+      required: false
+      description: >
+        Session-bound token from GET /auth/csrf. Mandatory on every write, but enforced by the CSRF
+        middleware (403 CSRF_INVALID), so the generated wrapper must not reject its absence first (400).
+      schema: { type: string }
+    IdeaId:
+      name: id
+      in: path
+      required: true
+      description: A malformed ID answers the uniform 404, not 400.
+      schema: { type: string, format: uuid }
+  responses:
+    Problem:
+      description: RFC 9457 problem; `code` is the stable contract (docs/API/error-codes.md)
+      content:
+        application/problem+json:
+          schema: { $ref: '#/components/schemas/Problem' }
+  schemas:
+    CsrfTokenResponse:
+      type: object
+      required: [token]
+      properties:
+        token: { type: string }
+    Problem:
+      type: object
+      required: [type, title, status, code]
+      properties:
+        type: { type: string, example: about:blank }
+        title: { type: string }
+        status: { type: integer }
+        code: { type: string, description: One of testdata/error-codes.json }
+        detail: { type: string }
+        requestId: { type: string, format: uuid }
+        errors:
+          type: array
+          items: { $ref: '#/components/schemas/FieldError' }
+    FieldError:
+      type: object
+      required: [field, code]
+      properties:
+        field: { type: string }
+        code: { type: string }
+        expected: { type: string }
+    Deadline:
+      type: object
+      required: [deadline, state, serverTime]
+      properties:
+        deadline: { type: string, format: date-time, nullable: true }
+        state: { type: string, enum: [NOT_OPEN, OPEN, CLOSED] }
+        serverTime: { type: string, format: date-time, description: Millisecond precision }
+    PersonRef:
+      type: object
+      required: [empNo, name]
+      properties:
+        empNo: { type: string }
+        name: { type: string }
+    IdeaSummary:
+      type: object
+      required: [id, name, category, org, direction, leader, memberCount, myRelation, createdAt, slidesUpdatedAt]
+      properties:
+        id: { type: string, format: uuid }
+        name: { type: string }
+        category: { type: string }
+        org: { type: string }
+        direction: { type: string }
+        leader: { $ref: '#/components/schemas/PersonRef' }
+        memberCount: { type: integer }
+        myRelation: { type: string, enum: [LEADER, MEMBER], nullable: true, description: null for Admin }
+        createdAt: { type: string, format: date-time }
+        slidesUpdatedAt: { type: string, format: date-time }
+    IdeaPage:
+      type: object
+      required: [items, page, size, total]
+      properties:
+        items:
+          type: array
+          items: { $ref: '#/components/schemas/IdeaSummary' }
+        page: { type: integer }
+        size: { type: integer }
+        total: { type: integer }
+    IdeaDetail:
+      type: object
+      required: [id, category, org, direction, name, summary, leader, members, pendingRequests, slides, expectedFilenameBase, createdAt, updatedAt, version]
+      properties:
+        id: { type: string, format: uuid }
+        category: { type: string }
+        org: { type: string }
+        direction: { type: string }
+        name: { type: string }
+        summary: { type: string }
+        leader: { $ref: '#/components/schemas/PersonRef' }
+        members:
+          type: array
+          items:
+            allOf:
+              - $ref: '#/components/schemas/PersonRef'
+              - type: object
+                required: [joinedAt]
+                properties:
+                  joinedAt: { type: string, format: date-time }
+        pendingRequests:
+          type: array
+          nullable: true
+          description: null unless Leader or Admin
+          items:
+            allOf:
+              - $ref: '#/components/schemas/PersonRef'
+              - type: object
+                required: [requestedAt]
+                properties:
+                  requestedAt: { type: string, format: date-time }
+        slides:
+          type: object
+          required: [ext, size, sha256, updatedAt, downloadFilename]
+          properties:
+            ext: { type: string }
+            size: { type: integer, format: int64 }
+            sha256: { type: string }
+            updatedAt: { type: string, format: date-time }
+            downloadFilename: { type: string }
+        expectedFilenameBase: { type: string, description: Without extension }
+        createdAt: { type: string, format: date-time }
+        updatedAt: { type: string, format: date-time }
+        version: { type: integer, format: int64 }

package/backend/cmd/server/main.go

@@ -0,0 +1,49 @@
+// Command server is the single deployable of the ESG Idea Contest backend.
+// Dependencies are wired by hand here (no DI framework).
+package main
+
+import (
+	"context"
+	"database/sql"
+	"fmt"
+	"os"
+	"os/signal"
+	"sync/atomic"
+	"syscall"
+
+	_ "github.com/go-sql-driver/mysql"
+
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/deadline"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/server"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/config"
+	"github.com/brian-huanggg/AwardRegistration/backend/internal/shared/web"
+)
+
+func main() {
+	if err := run(); err != nil {
+		fmt.Fprintln(os.Stderr, "fatal:", err)
+		os.Exit(1)
+	}
+}
+
+func run() error {
+	cfg, err := config.OS()
+	if err != nil {
+		return err
+	}
+	log := web.NewLogger(os.Stdout, cfg.LogLevel)
+
+	ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
+	defer stop()
+
+	db, err := sql.Open("mysql", cfg.DBDSN)
+	if err != nil {
+		return fmt.Errorf("ESG_DB_DSN: %w", err)
+	}
+	defer func() { _ = db.Close() }()
+
+	si := server.API{Deadline: deadline.Handler{Store: deadline.SQLStore{DB: db}}}
+
+	var ready atomic.Bool
+	return server.Run(ctx, cfg, log, server.NewPublic(log, server.Mount(si)), &ready, server.DBCheck(db))
+}

package/backend/db/migration/V001__init.sql

@@ -0,0 +1,25 @@
+-- V001 (B0-01): first schema slice.
+--   contest_setting  single-row table holding the submission deadline (PRD 5, 6.9)
+--   audit_log        skeleton only; B1-03 adds the remaining columns (expand-only)
+-- Times are database time in UTC; DATETIME has no zone, the DSN pins loc=UTC.
+
+CREATE TABLE contest_setting (
+    id         TINYINT UNSIGNED NOT NULL,
+    -- NULL = no deadline ever set (state NOT_OPEN). Second precision (PRD 6.9).
+    deadline   DATETIME(0)      NULL,
+    updated_at DATETIME(6)      NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+    PRIMARY KEY (id),
+    CONSTRAINT ck_contest_setting_single_row CHECK (id = 1)
+) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_bin;
+
+-- The one and only row; application code only ever UPDATEs it.
+INSERT INTO contest_setting (id, deadline) VALUES (1, NULL);
+
+CREATE TABLE audit_log (
+    -- Sequence for the optional hash chain (PRD 9 #5); Admin-visible only.
+    id          BIGINT UNSIGNED NOT NULL AUTO_INCREMENT,
+    -- Database time is the only clock (PRD 5).
+    occurred_at DATETIME(6)     NOT NULL DEFAULT CURRENT_TIMESTAMP(6),
+    PRIMARY KEY (id),
+    KEY ix_audit_log_occurred_at_id (occurred_at, id)
+) ENGINE = InnoDB DEFAULT CHARSET = utf8mb4 COLLATE = utf8mb4_bin;