Anti-Patterns from Legacy Systems

Purpose: This document catalogs critical mistakes from legacy systems that Framework M must not repeat.

Structure:

• ✅ Tackled = Already designed into Framework M (kept for reference)
• ⚠️ Remaining = Still needs explicit implementation

---

✅ TACKLED ISSUES

These issues have design decisions in place. Listed for reference only.

#	Issue	Solution	Where
1	name as Primary Key	id (UUID) as PK, name as unique index	Phase 01, 02
2	Global State (frappe.session.user)	Explicit user_context parameter	Phase 02
3	Metadata in Database	Code-first Pydantic models	Phase 01, 02
4	Synchronous/Blocking	Async native (Litestar + SQLAlchemy Async)	Phase 01
5	Monkey Patching	Entrypoint-based overrides	Phase 01
6	No Dependency Injection	dependency-injector library	Phase 01
7	Weak/No Type Hints	100% type hints, mypy --strict	Phase 01
8	Database-Specific Features	Portable SQLAlchemy types only	Phase 02
9	Implicit Transactions	Explicit transaction context managers	Phase 02
10	No Event Sourcing / Audit Trail	Every state change emits event	Phase 02, 04
11	Hard-coded Hooks	Event bus with multiple subscribers	Phase 04
12	Permission Checks in Business Logic	Repository-level enforcement	Phase 03
13	Session-Only Auth	Stateless JWT/header-based auth	Phase 03
14	eval()/exec() in User Input	JMESPath/SimpleEval only	Phase 10
15	Hard Delete Only	Soft delete with deleted_at	Phase 02
16	Opt-out API Exposure	Opt-in api_resource = True	Phase 03
17	Timezone-Naive Datetimes	DateTime(timezone=True) in SchemaMapper	Phase 02
18	N+1 Query Problem	load_children_for_parents() (select_in_loading) in GenericRepository	Phase 02, 10
19	Unbounded Queries	DEFAULT_LIMIT=20, MAX_LIMIT=1000 enforced	Phase 02
22	Unrestricted File Uploads	File DocType with extension whitelist, MIME validation	Phase 06
25	No Circuit Breaker (Email)	EmailQueue with async processing, not blocking	Phase 06
26	No API Versioning	URL-based versioning /api/v1/ prefix	Phase 03
29	Health Check Endpoints Missing	/studio/api/health endpoint implemented	Phase 07
30	Caching Layer Missing	RedisCacheAdapter + GenericRepository integration	Phase 02, 04
32	Over-Customization Upgrade Trap	Override mechanism + event-based extension	Phase 08
33	Missing/Manual Database Indexes	Automatic indexing of modified and Foreign Keys	Phase 10
23	Missing Request ID Tracing	Request context middleware injects request_id into structured logs	Phase 10
31	MariaDB-Specific Issues	DB-agnostic SQLAlchemy + connection pooling defaults (20/10/30/3600, pool_pre_ping)	Phase 02, 10
34	Post-Submission Editing (allow_on_submit)	Strict immutability for SUBMITTED docs via controller validation (ImmutableDocumentError)	Phase 02
27	Unsafe Deserialization	Prohibit pickle/yaml.load via Bandit (B301/B506) and 100% JSON-first logic.	Phase ALL
28	Missing CSRF Protection	Pluggable CSRFProtocol with Origin-header validation for all mutation methods.	Phase 11
20	Missing Rate Limiting	Identity-aware middleware with fallback to IP, and granular @rate_limit decorators.	Phase 03
21	Secrets in Logs	Pluggable ScrubbingLogic with case-insensitive redaction and Pydantic introspection.	Phase 10
35	Raw print() Statements	Governed output via CLIConsole (Human) and logging/structlog/LoggingProtocol.	Phase 10
24	No Idempotency Keys for Mutations	Pluggable IdempotencyProtocol via middleware with Redis/DB locking and response caching.	Phase 03

---

Checklist for Every Feature

Before implementing any feature, verify:

• Datetimes are timezone-aware (UTC)?
• Queries are paginated with max limit?
• No N+1 queries (use eager loading)?
• Rate limiting applied (if user-facing)?
• Secrets redacted from logs?
• No raw print() statements (use CLIConsole or module-level logs)?
• File uploads validated (extension + magic bytes)?
• Request ID propagated through logs?
• No pickle/unsafe YAML?
• CSRF protection on mutations?
• Circuit breaker on external calls?

Checklist for Frontend / UI Features

To maintain cross-platform compatibility and React Native support, all UI code must follow these principles:

• No Web-Exclusive DOM Primitives: Never use raw HTML tags like <div>, <span>, <button>, <input>, <form>, or <select>.
• Leverage @framework-m/ui Components: Always wrap layouts in Tamagui equivalents such as XStack, YStack, Paragraph, Button, Input, and Select.
• Eliminate Form Layouts: Avoid traditional <form> logic; implement state-driven hooks instead.