Pipeline/backend/.learnings/neo/LEARNINGS.md

Learnings Log - Neo (Forgejo Integration)

Key Decisions

1. Relationship Strategy

• Decision: Use explicit eager loading in API layer instead of SQLModel relationships
• Pattern: Fetch connection separately in API endpoints and attach to repository object
• Rationale: Simpler than dealing with SQLModel relationship type annotations and lazy loading complexity

2. Token Security

• Pattern: Store token_last_eight in DB, full token only in memory (client session)
• API Response: Only return has_token and token_last_eight, never the actual token
• Rationale: Follows security best practices for sensitive credentials

3. Base URL Normalization

• Pattern: Strip trailing slash and /api/v1 path from Forgejo base URL
• API: Input validation in schemas and service factory
• Rationale: Forgejo API typically uses base URL without /api/v1 suffix

4. Migration Management

• Pattern: Manual migration creation instead of autogenerate
• Rationale: Autogenerate failed due to environment setup issues; manual migration is more reliable

Code Patterns Established

ForgejoAPIClient

• Async context manager pattern: async with ForgejoAPIClient(...) as client:
• Token-based auth: Authorization: token <token> header
• User-Agent: Pipeline/ForgejoClient/1.0 for identification
• Short timeouts: connect=5s, read=30s

CRUD API Pattern

• All endpoints enforce org-scoped admin access
• Duplicate checks before create/update
• Connection validation ensures connection belongs to caller's org
• Safe response schema excludes sensitive data (token)

Model Pattern

• All models inherit from QueryModel
• Timestamps use app.core.time.utcnow()
• UUID primary keys with default_factory=uuid4