docs: Add SQLC type naming conventions and usage guidelines

- Introduced documentation on SQLC type naming conventions, emphasizing the importance of using schema-prefixed types in code.
- Provided examples of correct and incorrect usage of generated types in repository interfaces, service code, and tests.
- Updated related documentation files to ensure consistency and clarity regarding the use of SQLC-generated types.

Signed-off-by: Christian Melgarejo <cmelgarejo@users.noreply.github.com>

Author: cmelgarejo

.cursor/rules/30-data-sqlc.mdc

@@ -9,13 +9,37 @@ alwaysApply: false
   - SQL queries in `modules/<mod>/internal/db/query/*.sql`
   - generated SQLC store in `modules/<mod>/internal/db/store/`
 
+## SQLC Type Naming Conventions
+
+**IMPORTANT:** SQLC generates types with schema prefixes. Types are named using the pattern `{Schema}{TableName}`.
+
+- Tables in the `auth` schema generate types like:
+  - `auth.users` → `store.AuthUser` (NOT `store.User`)
+  - `auth.magic_codes` → `store.AuthMagicCode` (NOT `store.MagicCode`)
+  - `auth.sessions` → `store.AuthSession`
+  - `auth.oauth_states` → `store.AuthOauthState`
+
+- Always use the full prefixed type names in code:
+  ```go
+  // ✅ Correct
+  func GetUser(ctx context.Context, id string) (*store.AuthUser, error)
+  func GetMagicCode(ctx context.Context, code string) (*store.AuthMagicCode, error)
+
+  // ❌ Wrong
+  func GetUser(ctx context.Context, id string) (*store.User, error)
+  func GetMagicCode(ctx context.Context, code string) (*store.MagicCode, error)
+  ```
+
+- After running `make sqlc`, check `modules/<mod>/internal/db/store/models.go` to see the exact generated type names.
+
 ## Repository pattern
 
 - Flow: `store (sqlc)` → `repository` → `service` → `proto`.
 - The repository:
   - does not generate IDs
   - does not contain business logic
   - wraps external errors with context (`fmt.Errorf("...: %w", err)`)
+  - uses the correct SQLC-generated type names (with schema prefixes)
 
 ## Transactions
 

docs/MODULITH_ARCHITECTURE.md

@@ -1566,6 +1566,29 @@ func (r *SQLRepository) ListModules(ctx context.Context) ([]*store.Module, error
 }
 ```
 
+**SQLC Type Naming Conventions:**
+
+SQLC generates types with schema prefixes. Types follow the pattern `{Schema}{TableName}`:
+
+- Tables in the `auth` schema generate:
+  - `auth.users` → `store.AuthUser` (NOT `store.User`)
+  - `auth.magic_codes` → `store.AuthMagicCode` (NOT `store.MagicCode`)
+  - `auth.sessions` → `store.AuthSession`
+
+**Always use the full prefixed type names** in repository interfaces, service code, and tests:
+
+```go
+// ✅ Correct
+func GetUser(ctx context.Context, id string) (*store.AuthUser, error)
+func GetMagicCode(ctx context.Context, code string) (*store.AuthMagicCode, error)
+
+// ❌ Wrong - will cause "undefined: store.User" compilation errors
+func GetUser(ctx context.Context, id string) (*store.User, error)
+func GetMagicCode(ctx context.Context, code string) (*store.MagicCode, error)
+```
+
+After running `make sqlc`, check `modules/<mod>/internal/db/store/models.go` to see the exact generated type names.
+
 **Transaction Handling:**
 
 The `WithTx` method includes proper panic and error handling:

docs/TESTING_GUIDE.md

@@ -97,6 +97,39 @@ mockgen -source=modules/auth/internal/repository/repository.go \
 
 See `modules/auth/internal/service/service_mock_test.go` for examples.
 
+### SQLC Type Names in Tests
+
+**Important:** When writing tests that use SQLC-generated types, always use the correct type names with schema prefixes:
+
+```go
+// ✅ Correct - Use schema-prefixed types
+mockRepo.EXPECT().
+    GetUserByEmail(gomock.Any(), email).
+    Return(&store.AuthUser{
+        ID:    "user-123",
+        Email: sql.NullString{String: email, Valid: true},
+    }, nil)
+
+mockRepo.EXPECT().
+    GetValidMagicCodeByEmail(gomock.Any(), email, code).
+    Return(&store.AuthMagicCode{
+        Code:      code,
+        UserEmail: sql.NullString{String: email, Valid: true},
+    }, nil)
+
+// ❌ Wrong - Missing schema prefix
+mockRepo.EXPECT().
+    GetUserByEmail(gomock.Any(), email).
+    Return(&store.User{...}, nil)  // This will cause "undefined: store.User" error
+```
+
+SQLC generates types using the pattern `{Schema}{TableName}`:
+- `auth.users` → `store.AuthUser`
+- `auth.magic_codes` → `store.AuthMagicCode`
+- `auth.sessions` → `store.AuthSession`
+
+Always check `modules/<mod>/internal/db/store/models.go` after running `make sqlc` to see the exact generated type names.
+
 ## Integration Testing
 
 ### Testing Module Initialization