For AI Engineers

1. Crystal Clear Patterns

Only 4 patterns to memorize. LLMs produce consistent, correct code.

• Tables: `tb_entity`
• Views: `v_entity`
• IDs: UUID (never string, never int)
• Composition: JSONB with `jsonb_build_object()`

Impact: Models don't need 50 examples. 4 patterns = consistent generation.

2. Minimal Scaffolding

Compare code generation size:

# Generate resolvers + ORMs + types + validation
@resolver
async def user(info, id):
  user = db.query(...)
  return user

@resolver
async def user_posts(parent, info):
  posts = db.query(...)
  return posts

# + DataLoader setup
# + Cache invalidation
# + Error handling

~80 lines of generated code per type

# SQL view (human-written once)
CREATE VIEW v_user_with_posts AS ...

# Type definition
@fraiseql.type
class User:
  id: ID
  name: str
  posts: list[Post]

# Query resolver
@fraiseql.query(sql_source="v_user_with_posts")
def user(id: ID) -> User:
  pass

~15 lines of generated code per type

Impact: 5x less code to generate = 5x fewer tokens = faster, cheaper generations.

3. Deterministic Verification

LLMs can verify correctness through compilation:

# LLM generates code
# System compiles with: fraiseql build

# If any patterns wrong:
ERROR: Table 'tb_user' has id field as STRING
Expected: UUID

# LLM sees error, fixes, regenerates
# ✓ Loop terminates quickly with correct code

Impact: No guessing. Compile-time feedback = faster iteration.

4. Predictable Performance

LLMs don't need to worry about N+1 queries:

• ✅ One view = one query (always)
• ✅ No hidden performance footguns
• ✅ No need to explain DataLoader patterns
• ✅ Composition happens at database level (reliable)

Impact: Generated code is production-ready without performance audits.

5. Small API Surface

FraiseQL handles only one thing: map views to types.

Everything else is standard tools (auth, caching, databases).

# What LLMs need to know:
✓ SQL: Create views with JSONB composition
✓ Types: Define schema types matching views
✓ Queries: Declare sql_source="v_name"
✓ Mutations: Declare sql_source="fn_name", operation="CREATE|UPDATE|DELETE"

# What LLMs DON'T need to know:
✗ Resolver patterns (there are none)
✗ DataLoader configuration (not needed)
✗ N+1 prevention strategies (built-in)
✗ Cache invalidation (optional, standard Redis)
✗ Query batching (happens at DB level)

Impact: Smaller knowledge base = fewer tokens + fewer hallucinations.