diff --git a/internal/repository/postgres/db.go b/internal/repository/postgres/db.go
index e546ecca..be860a38 100644
--- a/internal/repository/postgres/db.go
+++ b/internal/repository/postgres/db.go
@@ -16,6 +16,8 @@ type DBTX interface {
 	QueryRowContext(context.Context, string, ...interface{}) *sql.Row
 }
 
+// New returns a *Queries configured to use the provided DBTX for executing database operations.
+// The returned *Queries will use db as its database handle for all query method calls.
 func New(db DBTX) *Queries {
 	return &Queries{db: db}
 }
diff --git a/internal/repository/postgres/store.go b/internal/repository/postgres/store.go
index ed4bbb73..17091f13 100644
--- a/internal/repository/postgres/store.go
+++ b/internal/repository/postgres/store.go
@@ -14,7 +14,7 @@ type Store struct {
 	q *Queries
 }
 
-// NewStore wraps a *Queries to satisfy repository.Store.
+// NewStore returns a repository.Store backed by the provided *Queries.
 func NewStore(q *Queries) repository.Store {
 	return &Store{q: q}
 }
@@ -23,6 +23,8 @@ var errorMap = map[error]error{
 	sql.ErrNoRows: repository.ErrNotFound,
 }
 
+// mapErr maps known database errors to repository-level errors using the package-level errorMap.
+// It uses errors.Is to match (so wrapped errors are recognized) and returns the original error if no mapping applies.
 func mapErr(err error) error {
 	for from, to := range errorMap {
 		if errors.Is(err, from) {