docs(project): add reference Python/Flask implementation

Previous version of Tanabata used as visual and functional reference
for the new Go + SvelteKit rewrite.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

docs/reference/backend/db/db.go

@@ -0,0 +1,79 @@
+package db
+
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net/http"
+	"time"
+
+	"github.com/jackc/pgx/v5"
+	"github.com/jackc/pgx/v5/pgconn"
+	"github.com/jackc/pgx/v5/pgxpool"
+)
+
+var connPool *pgxpool.Pool
+
+func InitDB(connString string) error {
+	poolConfig, err := pgxpool.ParseConfig(connString)
+	if err != nil {
+		return fmt.Errorf("error while parsing connection string: %w", err)
+	}
+
+	poolConfig.MaxConns = 100
+	poolConfig.MinConns = 0
+	poolConfig.MaxConnLifetime = time.Hour
+	poolConfig.HealthCheckPeriod = 30 * time.Second
+
+	connPool, err = pgxpool.NewWithConfig(context.Background(), poolConfig)
+	if err != nil {
+		return fmt.Errorf("error while initializing DB connections pool: %w", err)
+	}
+	return nil
+}
+
+func transaction(handler func(context.Context, pgx.Tx) (statusCode int, err error)) (statusCode int, err error) {
+	ctx := context.Background()
+	tx, err := connPool.Begin(ctx)
+	if err != nil {
+		statusCode = http.StatusInternalServerError
+		return
+	}
+	statusCode, err = handler(ctx, tx)
+	if err != nil {
+		tx.Rollback(ctx)
+		return
+	}
+	err = tx.Commit(ctx)
+	if err != nil {
+		statusCode = http.StatusInternalServerError
+	}
+	return
+}
+
+// Handle database error
+func handleDBError(errIn error) (statusCode int, err error) {
+	if errIn == nil {
+		statusCode = http.StatusOK
+		return
+	}
+	if errors.Is(errIn, pgx.ErrNoRows) {
+		err = fmt.Errorf("not found")
+		statusCode = http.StatusNotFound
+		return
+	}
+	var pgErr *pgconn.PgError
+	if errors.As(errIn, &pgErr) {
+		switch pgErr.Code {
+		case "22P02", "22007": // Invalid data format
+			err = fmt.Errorf("%s", pgErr.Message)
+			statusCode = http.StatusBadRequest
+			return
+		case "23505": // Unique constraint violation
+			err = fmt.Errorf("already exists")
+			statusCode = http.StatusConflict
+			return
+		}
+	}
+	return http.StatusInternalServerError, errIn
+}

docs/reference/backend/db/utils.go

@@ -0,0 +1,53 @@
+package db
+
+import (
+	"fmt"
+	"net/http"
+	"strconv"
+	"strings"
+)
+
+// Convert "filter" URL param to SQL "WHERE" condition
+func filterToSQL(filter string) (sql string, statusCode int, err error) {
+	// filterTokens := strings.Split(string(filter), ";")
+	sql = "(true)"
+	return
+}
+
+// Convert "sort" URL param to SQL "ORDER BY"
+func sortToSQL(sort string) (sql string, statusCode int, err error) {
+	if sort == "" {
+		return
+	}
+	sortOptions := strings.Split(sort, ",")
+	sql = " ORDER BY "
+	for i, sortOption := range sortOptions {
+		sortOrder := sortOption[:1]
+		sortColumn := sortOption[1:]
+		// parse sorting order marker
+		switch sortOrder {
+		case "+":
+			sortOrder = "ASC"
+		case "-":
+			sortOrder = "DESC"
+		default:
+			err = fmt.Errorf("invalid sorting order mark: %q", sortOrder)
+			statusCode = http.StatusBadRequest
+			return
+		}
+		// validate sorting column
+		var n int
+		n, err = strconv.Atoi(sortColumn)
+		if err != nil || n < 0 {
+			err = fmt.Errorf("invalid sorting column: %q", sortColumn)
+			statusCode = http.StatusBadRequest
+			return
+		}
+		// add sorting option to query
+		if i > 0 {
+			sql += ","
+		}
+		sql += fmt.Sprintf("%s %s NULLS LAST", sortColumn, sortOrder)
+	}
+	return
+}