diff --git a/.cursor/commands/analyze.md b/.cursor/commands/analyze.md
new file mode 100644
index 0000000000..f4c1a7bd97
--- /dev/null
+++ b/.cursor/commands/analyze.md
@@ -0,0 +1,101 @@
+---
+description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation.
+---
+
+The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
+
+User input:
+
+$ARGUMENTS
+
+Goal: Identify inconsistencies, duplications, ambiguities, and underspecified items across the three core artifacts (`spec.md`, `plan.md`, `tasks.md`) before implementation. This command MUST run only after `/tasks` has successfully produced a complete `tasks.md`.
+
+STRICTLY READ-ONLY: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands would be invoked manually).
+
+Constitution Authority: The project constitution (`.specify/memory/constitution.md`) is **non-negotiable** within this analysis scope. Constitution conflicts are automatically CRITICAL and require adjustment of the spec, plan, or tasks—not dilution, reinterpretation, or silent ignoring of the principle. If a principle itself needs to change, that must occur in a separate, explicit constitution update outside `/analyze`.
+
+Execution steps:
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` once from repo root and parse JSON for FEATURE_DIR and AVAILABLE_DOCS. Derive absolute paths:
+   - SPEC = FEATURE_DIR/spec.md
+   - PLAN = FEATURE_DIR/plan.md
+   - TASKS = FEATURE_DIR/tasks.md
+   Abort with an error message if any required file is missing (instruct the user to run missing prerequisite command).
+
+2. Load artifacts:
+   - Parse spec.md sections: Overview/Context, Functional Requirements, Non-Functional Requirements, User Stories, Edge Cases (if present).
+   - Parse plan.md: Architecture/stack choices, Data Model references, Phases, Technical constraints.
+   - Parse tasks.md: Task IDs, descriptions, phase grouping, parallel markers [P], referenced file paths.
+   - Load constitution `.specify/memory/constitution.md` for principle validation.
+
+3. Build internal semantic models:
+   - Requirements inventory: Each functional + non-functional requirement with a stable key (derive slug based on imperative phrase; e.g., "User can upload file" -> `user-can-upload-file`).
+   - User story/action inventory.
+   - Task coverage mapping: Map each task to one or more requirements or stories (inference by keyword / explicit reference patterns like IDs or key phrases).
+   - Constitution rule set: Extract principle names and any MUST/SHOULD normative statements.
+
+4. Detection passes:
+   A. Duplication detection:
+      - Identify near-duplicate requirements. Mark lower-quality phrasing for consolidation.
+   B. Ambiguity detection:
+      - Flag vague adjectives (fast, scalable, secure, intuitive, robust) lacking measurable criteria.
+      - Flag unresolved placeholders (TODO, TKTK, ???, <placeholder>, etc.).
+   C. Underspecification:
+      - Requirements with verbs but missing object or measurable outcome.
+      - User stories missing acceptance criteria alignment.
+      - Tasks referencing files or components not defined in spec/plan.
+   D. Constitution alignment:
+      - Any requirement or plan element conflicting with a MUST principle.
+      - Missing mandated sections or quality gates from constitution.
+   E. Coverage gaps:
+      - Requirements with zero associated tasks.
+      - Tasks with no mapped requirement/story.
+      - Non-functional requirements not reflected in tasks (e.g., performance, security).
+   F. Inconsistency:
+      - Terminology drift (same concept named differently across files).
+      - Data entities referenced in plan but absent in spec (or vice versa).
+      - Task ordering contradictions (e.g., integration tasks before foundational setup tasks without dependency note).
+      - Conflicting requirements (e.g., one requires to use Next.js while other says to use Vue as the framework).
+
+5. Severity assignment heuristic:
+   - CRITICAL: Violates constitution MUST, missing core spec artifact, or requirement with zero coverage that blocks baseline functionality.
+   - HIGH: Duplicate or conflicting requirement, ambiguous security/performance attribute, untestable acceptance criterion.
+   - MEDIUM: Terminology drift, missing non-functional task coverage, underspecified edge case.
+   - LOW: Style/wording improvements, minor redundancy not affecting execution order.
+
+6. Produce a Markdown report (no file writes) with sections:
+
+   ### Specification Analysis Report
+   | ID | Category | Severity | Location(s) | Summary | Recommendation |
+   |----|----------|----------|-------------|---------|----------------|
+   | A1 | Duplication | HIGH | spec.md:L120-134 | Two similar requirements ... | Merge phrasing; keep clearer version |
+   (Add one row per finding; generate stable IDs prefixed by category initial.)
+
+   Additional subsections:
+   - Coverage Summary Table:
+     | Requirement Key | Has Task? | Task IDs | Notes |
+   - Constitution Alignment Issues (if any)
+   - Unmapped Tasks (if any)
+   - Metrics:
+     * Total Requirements
+     * Total Tasks
+     * Coverage % (requirements with >=1 task)
+     * Ambiguity Count
+     * Duplication Count
+     * Critical Issues Count
+
+7. At end of report, output a concise Next Actions block:
+   - If CRITICAL issues exist: Recommend resolving before `/implement`.
+   - If only LOW/MEDIUM: User may proceed, but provide improvement suggestions.
+   - Provide explicit command suggestions: e.g., "Run /specify with refinement", "Run /plan to adjust architecture", "Manually edit tasks.md to add coverage for 'performance-metrics'".
+
+8. Ask the user: "Would you like me to suggest concrete remediation edits for the top N issues?" (Do NOT apply them automatically.)
+
+Behavior rules:
+- NEVER modify files.
+- NEVER hallucinate missing sections—if absent, report them.
+- KEEP findings deterministic: if rerun without changes, produce consistent IDs and counts.
+- LIMIT total findings in the main table to 50; aggregate remainder in a summarized overflow note.
+- If zero issues found, emit a success report with coverage statistics and proceed recommendation.
+
+Context: $ARGUMENTS
diff --git a/.cursor/commands/clarify.md b/.cursor/commands/clarify.md
new file mode 100644
index 0000000000..26ff530bd1
--- /dev/null
+++ b/.cursor/commands/clarify.md
@@ -0,0 +1,158 @@
+---
+description: Identify underspecified areas in the current feature spec by asking up to 5 highly targeted clarification questions and encoding answers back into the spec.
+---
+
+The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
+
+User input:
+
+$ARGUMENTS
+
+Goal: Detect and reduce ambiguity or missing decision points in the active feature specification and record the clarifications directly in the spec file.
+
+Note: This clarification workflow is expected to run (and be completed) BEFORE invoking `/plan`. If the user explicitly states they are skipping clarification (e.g., exploratory spike), you may proceed, but must warn that downstream rework risk increases.
+
+Execution steps:
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --paths-only` from repo root **once** (combined `--json --paths-only` mode / `-Json -PathsOnly`). Parse minimal JSON payload fields:
+   - `FEATURE_DIR`
+   - `FEATURE_SPEC`
+   - (Optionally capture `IMPL_PLAN`, `TASKS` for future chained flows.)
+   - If JSON parsing fails, abort and instruct user to re-run `/specify` or verify feature branch environment.
+
+2. Load the current spec file. Perform a structured ambiguity & coverage scan using this taxonomy. For each category, mark status: Clear / Partial / Missing. Produce an internal coverage map used for prioritization (do not output raw map unless no questions will be asked).
+
+   Functional Scope & Behavior:
+   - Core user goals & success criteria
+   - Explicit out-of-scope declarations
+   - User roles / personas differentiation
+
+   Domain & Data Model:
+   - Entities, attributes, relationships
+   - Identity & uniqueness rules
+   - Lifecycle/state transitions
+   - Data volume / scale assumptions
+
+   Interaction & UX Flow:
+   - Critical user journeys / sequences
+   - Error/empty/loading states
+   - Accessibility or localization notes
+
+   Non-Functional Quality Attributes:
+   - Performance (latency, throughput targets)
+   - Scalability (horizontal/vertical, limits)
+   - Reliability & availability (uptime, recovery expectations)
+   - Observability (logging, metrics, tracing signals)
+   - Security & privacy (authN/Z, data protection, threat assumptions)
+   - Compliance / regulatory constraints (if any)
+
+   Integration & External Dependencies:
+   - External services/APIs and failure modes
+   - Data import/export formats
+   - Protocol/versioning assumptions
+
+   Edge Cases & Failure Handling:
+   - Negative scenarios
+   - Rate limiting / throttling
+   - Conflict resolution (e.g., concurrent edits)
+
+   Constraints & Tradeoffs:
+   - Technical constraints (language, storage, hosting)
+   - Explicit tradeoffs or rejected alternatives
+
+   Terminology & Consistency:
+   - Canonical glossary terms
+   - Avoided synonyms / deprecated terms
+
+   Completion Signals:
+   - Acceptance criteria testability
+   - Measurable Definition of Done style indicators
+
+   Misc / Placeholders:
+   - TODO markers / unresolved decisions
+   - Ambiguous adjectives ("robust", "intuitive") lacking quantification
+
+   For each category with Partial or Missing status, add a candidate question opportunity unless:
+   - Clarification would not materially change implementation or validation strategy
+   - Information is better deferred to planning phase (note internally)
+
+3. Generate (internally) a prioritized queue of candidate clarification questions (maximum 5). Do NOT output them all at once. Apply these constraints:
+    - Maximum of 5 total questions across the whole session.
+    - Each question must be answerable with EITHER:
+       * A short multiple‑choice selection (2–5 distinct, mutually exclusive options), OR
+       * A one-word / short‑phrase answer (explicitly constrain: "Answer in <=5 words").
+   - Only include questions whose answers materially impact architecture, data modeling, task decomposition, test design, UX behavior, operational readiness, or compliance validation.
+   - Ensure category coverage balance: attempt to cover the highest impact unresolved categories first; avoid asking two low-impact questions when a single high-impact area (e.g., security posture) is unresolved.
+   - Exclude questions already answered, trivial stylistic preferences, or plan-level execution details (unless blocking correctness).
+   - Favor clarifications that reduce downstream rework risk or prevent misaligned acceptance tests.
+   - If more than 5 categories remain unresolved, select the top 5 by (Impact * Uncertainty) heuristic.
+
+4. Sequential questioning loop (interactive):
+    - Present EXACTLY ONE question at a time.
+    - For multiple‑choice questions render options as a Markdown table:
+
+       | Option | Description |
+       |--------|-------------|
+       | A | <Option A description> |
+       | B | <Option B description> |
+       | C | <Option C description> | (add D/E as needed up to 5)
+       | Short | Provide a different short answer (<=5 words) | (Include only if free-form alternative is appropriate)
+
+    - For short‑answer style (no meaningful discrete options), output a single line after the question: `Format: Short answer (<=5 words)`.
+    - After the user answers:
+       * Validate the answer maps to one option or fits the <=5 word constraint.
+       * If ambiguous, ask for a quick disambiguation (count still belongs to same question; do not advance).
+       * Once satisfactory, record it in working memory (do not yet write to disk) and move to the next queued question.
+    - Stop asking further questions when:
+       * All critical ambiguities resolved early (remaining queued items become unnecessary), OR
+       * User signals completion ("done", "good", "no more"), OR
+       * You reach 5 asked questions.
+    - Never reveal future queued questions in advance.
+    - If no valid questions exist at start, immediately report no critical ambiguities.
+
+5. Integration after EACH accepted answer (incremental update approach):
+    - Maintain in-memory representation of the spec (loaded once at start) plus the raw file contents.
+    - For the first integrated answer in this session:
+       * Ensure a `## Clarifications` section exists (create it just after the highest-level contextual/overview section per the spec template if missing).
+       * Under it, create (if not present) a `### Session YYYY-MM-DD` subheading for today.
+    - Append a bullet line immediately after acceptance: `- Q: <question> → A: <final answer>`.
+    - Then immediately apply the clarification to the most appropriate section(s):
+       * Functional ambiguity → Update or add a bullet in Functional Requirements.
+       * User interaction / actor distinction → Update User Stories or Actors subsection (if present) with clarified role, constraint, or scenario.
+       * Data shape / entities → Update Data Model (add fields, types, relationships) preserving ordering; note added constraints succinctly.
+       * Non-functional constraint → Add/modify measurable criteria in Non-Functional / Quality Attributes section (convert vague adjective to metric or explicit target).
+       * Edge case / negative flow → Add a new bullet under Edge Cases / Error Handling (or create such subsection if template provides placeholder for it).
+       * Terminology conflict → Normalize term across spec; retain original only if necessary by adding `(formerly referred to as "X")` once.
+    - If the clarification invalidates an earlier ambiguous statement, replace that statement instead of duplicating; leave no obsolete contradictory text.
+    - Save the spec file AFTER each integration to minimize risk of context loss (atomic overwrite).
+    - Preserve formatting: do not reorder unrelated sections; keep heading hierarchy intact.
+    - Keep each inserted clarification minimal and testable (avoid narrative drift).
+
+6. Validation (performed after EACH write plus final pass):
+   - Clarifications session contains exactly one bullet per accepted answer (no duplicates).
+   - Total asked (accepted) questions ≤ 5.
+   - Updated sections contain no lingering vague placeholders the new answer was meant to resolve.
+   - No contradictory earlier statement remains (scan for now-invalid alternative choices removed).
+   - Markdown structure valid; only allowed new headings: `## Clarifications`, `### Session YYYY-MM-DD`.
+   - Terminology consistency: same canonical term used across all updated sections.
+
+7. Write the updated spec back to `FEATURE_SPEC`.
+
+8. Report completion (after questioning loop ends or early termination):
+   - Number of questions asked & answered.
+   - Path to updated spec.
+   - Sections touched (list names).
+   - Coverage summary table listing each taxonomy category with Status: Resolved (was Partial/Missing and addressed), Deferred (exceeds question quota or better suited for planning), Clear (already sufficient), Outstanding (still Partial/Missing but low impact).
+   - If any Outstanding or Deferred remain, recommend whether to proceed to `/plan` or run `/clarify` again later post-plan.
+   - Suggested next command.
+
+Behavior rules:
+- If no meaningful ambiguities found (or all potential questions would be low-impact), respond: "No critical ambiguities detected worth formal clarification." and suggest proceeding.
+- If spec file missing, instruct user to run `/specify` first (do not create a new spec here).
+- Never exceed 5 total asked questions (clarification retries for a single question do not count as new questions).
+- Avoid speculative tech stack questions unless the absence blocks functional clarity.
+- Respect user early termination signals ("stop", "done", "proceed").
+ - If no questions asked due to full coverage, output a compact coverage summary (all categories Clear) then suggest advancing.
+ - If quota reached with unresolved high-impact categories remaining, explicitly flag them under Deferred with rationale.
+
+Context for prioritization: $ARGUMENTS
diff --git a/.cursor/commands/constitution.md b/.cursor/commands/constitution.md
new file mode 100644
index 0000000000..765867e600
--- /dev/null
+++ b/.cursor/commands/constitution.md
@@ -0,0 +1,73 @@
+---
+description: Create or update the project constitution from interactive or provided principle inputs, ensuring all dependent templates stay in sync.
+---
+
+The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
+
+User input:
+
+$ARGUMENTS
+
+You are updating the project constitution at `.specify/memory/constitution.md`. This file is a TEMPLATE containing placeholder tokens in square brackets (e.g. `[PROJECT_NAME]`, `[PRINCIPLE_1_NAME]`). Your job is to (a) collect/derive concrete values, (b) fill the template precisely, and (c) propagate any amendments across dependent artifacts.
+
+Follow this execution flow:
+
+1. Load the existing constitution template at `.specify/memory/constitution.md`.
+   - Identify every placeholder token of the form `[ALL_CAPS_IDENTIFIER]`.
+   **IMPORTANT**: The user might require less or more principles than the ones used in the template. If a number is specified, respect that - follow the general template. You will update the doc accordingly.
+
+2. Collect/derive values for placeholders:
+   - If user input (conversation) supplies a value, use it.
+   - Otherwise infer from existing repo context (README, docs, prior constitution versions if embedded).
+   - For governance dates: `RATIFICATION_DATE` is the original adoption date (if unknown ask or mark TODO), `LAST_AMENDED_DATE` is today if changes are made, otherwise keep previous.
+   - `CONSTITUTION_VERSION` must increment according to semantic versioning rules:
+     * MAJOR: Backward incompatible governance/principle removals or redefinitions.
+     * MINOR: New principle/section added or materially expanded guidance.
+     * PATCH: Clarifications, wording, typo fixes, non-semantic refinements.
+   - If version bump type ambiguous, propose reasoning before finalizing.
+
+3. Draft the updated constitution content:
+   - Replace every placeholder with concrete text (no bracketed tokens left except intentionally retained template slots that the project has chosen not to define yet—explicitly justify any left).
+   - Preserve heading hierarchy and comments can be removed once replaced unless they still add clarifying guidance.
+   - Ensure each Principle section: succinct name line, paragraph (or bullet list) capturing non‑negotiable rules, explicit rationale if not obvious.
+   - Ensure Governance section lists amendment procedure, versioning policy, and compliance review expectations.
+
+4. Consistency propagation checklist (convert prior checklist into active validations):
+   - Read `.specify/templates/plan-template.md` and ensure any "Constitution Check" or rules align with updated principles.
+   - Read `.specify/templates/spec-template.md` for scope/requirements alignment—update if constitution adds/removes mandatory sections or constraints.
+   - Read `.specify/templates/tasks-template.md` and ensure task categorization reflects new or removed principle-driven task types (e.g., observability, versioning, testing discipline).
+   - Read each command file in `.specify/templates/commands/*.md` (including this one) to verify no outdated references (agent-specific names like CLAUDE only) remain when generic guidance is required.
+   - Read any runtime guidance docs (e.g., `README.md`, `docs/quickstart.md`, or agent-specific guidance files if present). Update references to principles changed.
+
+5. Produce a Sync Impact Report (prepend as an HTML comment at top of the constitution file after update):
+   - Version change: old → new
+   - List of modified principles (old title → new title if renamed)
+   - Added sections
+   - Removed sections
+   - Templates requiring updates (✅ updated / ⚠ pending) with file paths
+   - Follow-up TODOs if any placeholders intentionally deferred.
+
+6. Validation before final output:
+   - No remaining unexplained bracket tokens.
+   - Version line matches report.
+   - Dates ISO format YYYY-MM-DD.
+   - Principles are declarative, testable, and free of vague language ("should" → replace with MUST/SHOULD rationale where appropriate).
+
+7. Write the completed constitution back to `.specify/memory/constitution.md` (overwrite).
+
+8. Output a final summary to the user with:
+   - New version and bump rationale.
+   - Any files flagged for manual follow-up.
+   - Suggested commit message (e.g., `docs: amend constitution to vX.Y.Z (principle additions + governance update)`).
+
+Formatting & Style Requirements:
+- Use Markdown headings exactly as in the template (do not demote/promote levels).
+- Wrap long rationale lines to keep readability (<100 chars ideally) but do not hard enforce with awkward breaks.
+- Keep a single blank line between sections.
+- Avoid trailing whitespace.
+
+If the user supplies partial updates (e.g., only one principle revision), still perform validation and version decision steps.
+
+If critical info missing (e.g., ratification date truly unknown), insert `TODO(<FIELD_NAME>): explanation` and include in the Sync Impact Report under deferred items.
+
+Do not create a new template; always operate on the existing `.specify/memory/constitution.md` file.
diff --git a/.cursor/commands/implement.md b/.cursor/commands/implement.md
new file mode 100644
index 0000000000..003dce9191
--- /dev/null
+++ b/.cursor/commands/implement.md
@@ -0,0 +1,56 @@
+---
+description: Execute the implementation plan by processing and executing all tasks defined in tasks.md
+---
+
+The user input can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
+
+User input:
+
+$ARGUMENTS
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
+
+2. Load and analyze the implementation context:
+   - **REQUIRED**: Read tasks.md for the complete task list and execution plan
+   - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure
+   - **IF EXISTS**: Read data-model.md for entities and relationships
+   - **IF EXISTS**: Read contracts/ for API specifications and test requirements
+   - **IF EXISTS**: Read research.md for technical decisions and constraints
+   - **IF EXISTS**: Read quickstart.md for integration scenarios
+
+3. Parse tasks.md structure and extract:
+   - **Task phases**: Setup, Tests, Core, Integration, Polish
+   - **Task dependencies**: Sequential vs parallel execution rules
+   - **Task details**: ID, description, file paths, parallel markers [P]
+   - **Execution flow**: Order and dependency requirements
+
+4. Execute implementation following the task plan:
+   - **Phase-by-phase execution**: Complete each phase before moving to the next
+   - **Respect dependencies**: Run sequential tasks in order, parallel tasks [P] can run together  
+   - **Follow TDD approach**: Execute test tasks before their corresponding implementation tasks
+   - **File-based coordination**: Tasks affecting the same files must run sequentially
+   - **Validation checkpoints**: Verify each phase completion before proceeding
+
+5. Implementation execution rules:
+   - **Setup first**: Initialize project structure, dependencies, configuration
+   - **Tests before code**: If you need to write tests for contracts, entities, and integration scenarios
+   - **Core development**: Implement models, services, CLI commands, endpoints
+   - **Integration work**: Database connections, middleware, logging, external services
+   - **Polish and validation**: Unit tests, performance optimization, documentation
+
+6. Progress tracking and error handling:
+   - Report progress after each completed task
+   - Halt execution if any non-parallel task fails
+   - For parallel tasks [P], continue with successful tasks, report failed ones
+   - Provide clear error messages with context for debugging
+   - Suggest next steps if implementation cannot proceed
+   - **IMPORTANT** For completed tasks, make sure to mark the task off as [X] in the tasks file.
+
+7. Completion validation:
+   - Verify all required tasks are completed
+   - Check that implemented features match the original specification
+   - Validate that tests pass and coverage meets requirements
+   - Confirm the implementation follows the technical plan
+   - Report final status with summary of completed work
+
+Note: This command assumes a complete task breakdown exists in tasks.md. If tasks are incomplete or missing, suggest running `/tasks` first to regenerate the task list.
diff --git a/.cursor/commands/plan.md b/.cursor/commands/plan.md
new file mode 100644
index 0000000000..23c020ac0a
--- /dev/null
+++ b/.cursor/commands/plan.md
@@ -0,0 +1,43 @@
+---
+description: Execute the implementation planning workflow using the plan template to generate design artifacts.
+---
+
+The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
+
+User input:
+
+$ARGUMENTS
+
+Given the implementation details provided as an argument, do this:
+
+1. Run `.specify/scripts/bash/setup-plan.sh --json` from the repo root and parse JSON for FEATURE_SPEC, IMPL_PLAN, SPECS_DIR, BRANCH. All future file paths must be absolute.
+   - BEFORE proceeding, inspect FEATURE_SPEC for a `## Clarifications` section with at least one `Session` subheading. If missing or clearly ambiguous areas remain (vague adjectives, unresolved critical choices), PAUSE and instruct the user to run `/clarify` first to reduce rework. Only continue if: (a) Clarifications exist OR (b) an explicit user override is provided (e.g., "proceed without clarification"). Do not attempt to fabricate clarifications yourself.
+2. Read and analyze the feature specification to understand:
+   - The feature requirements and user stories
+   - Functional and non-functional requirements
+   - Success criteria and acceptance criteria
+   - Any technical constraints or dependencies mentioned
+
+3. Read the constitution at `.specify/memory/constitution.md` to understand constitutional requirements.
+
+4. Execute the implementation plan template:
+   - Load `.specify/templates/plan-template.md` (already copied to IMPL_PLAN path)
+   - Set Input path to FEATURE_SPEC
+   - Run the Execution Flow (main) function steps 1-9
+   - The template is self-contained and executable
+   - Follow error handling and gate checks as specified
+   - Let the template guide artifact generation in $SPECS_DIR:
+     * Phase 0 generates research.md
+     * Phase 1 generates data-model.md, contracts/, quickstart.md
+     * Phase 2 generates tasks.md
+   - Incorporate user-provided details from arguments into Technical Context: $ARGUMENTS
+   - Update Progress Tracking as you complete each phase
+
+5. Verify execution completed:
+   - Check Progress Tracking shows all phases complete
+   - Ensure all required artifacts were generated
+   - Confirm no ERROR states in execution
+
+6. Report results with branch name, file paths, and generated artifacts.
+
+Use absolute paths with the repository root for all file operations to avoid path issues.
diff --git a/.cursor/commands/specify.md b/.cursor/commands/specify.md
new file mode 100644
index 0000000000..0f92105af5
--- /dev/null
+++ b/.cursor/commands/specify.md
@@ -0,0 +1,21 @@
+---
+description: Create or update the feature specification from a natural language feature description.
+---
+
+The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
+
+User input:
+
+$ARGUMENTS
+
+The text the user typed after `/specify` in the triggering message **is** the feature description. Assume you always have it available in this conversation even if `$ARGUMENTS` appears literally below. Do not ask the user to repeat it unless they provided an empty command.
+
+Given that feature description, do this:
+
+1. Run the script `.specify/scripts/bash/create-new-feature.sh --json "$ARGUMENTS"` from repo root and parse its JSON output for BRANCH_NAME and SPEC_FILE. All file paths must be absolute.
+  **IMPORTANT** You must only ever run this script once. The JSON is provided in the terminal as output - always refer to it to get the actual content you're looking for.
+2. Load `.specify/templates/spec-template.md` to understand required sections.
+3. Write the specification to SPEC_FILE using the template structure, replacing placeholders with concrete details derived from the feature description (arguments) while preserving section order and headings.
+4. Report completion with branch name, spec file path, and readiness for the next phase.
+
+Note: The script creates and checks out the new branch and initializes the spec file before writing.
diff --git a/.cursor/commands/tasks.md b/.cursor/commands/tasks.md
new file mode 100644
index 0000000000..a026e93fb0
--- /dev/null
+++ b/.cursor/commands/tasks.md
@@ -0,0 +1,62 @@
+---
+description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts.
+---
+
+The user input to you can be provided directly by the agent or as a command argument - you **MUST** consider it before proceeding with the prompt (if not empty).
+
+User input:
+
+$ARGUMENTS
+
+1. Run `.specify/scripts/bash/check-prerequisites.sh --json` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute.
+2. Load and analyze available design documents:
+   - Always read plan.md for tech stack and libraries
+   - IF EXISTS: Read data-model.md for entities
+   - IF EXISTS: Read contracts/ for API endpoints
+   - IF EXISTS: Read research.md for technical decisions
+   - IF EXISTS: Read quickstart.md for test scenarios
+
+   Note: Not all projects have all documents. For example:
+   - CLI tools might not have contracts/
+   - Simple libraries might not need data-model.md
+   - Generate tasks based on what's available
+
+3. Generate tasks following the template:
+   - Use `.specify/templates/tasks-template.md` as the base
+   - Replace example tasks with actual tasks based on:
+     * **Setup tasks**: Project init, dependencies, linting
+     * **Test tasks [P]**: One per contract, one per integration scenario
+     * **Core tasks**: One per entity, service, CLI command, endpoint
+     * **Integration tasks**: DB connections, middleware, logging
+     * **Polish tasks [P]**: Unit tests, performance, docs
+
+4. Task generation rules:
+   - Each contract file → contract test task marked [P]
+   - Each entity in data-model → model creation task marked [P]
+   - Each endpoint → implementation task (not parallel if shared files)
+   - Each user story → integration test marked [P]
+   - Different files = can be parallel [P]
+   - Same file = sequential (no [P])
+
+5. Order tasks by dependencies:
+   - Setup before everything
+   - Tests before implementation (TDD)
+   - Models before services
+   - Services before endpoints
+   - Core before integration
+   - Everything before polish
+
+6. Include parallel execution examples:
+   - Group [P] tasks that can run together
+   - Show actual Task agent commands
+
+7. Create FEATURE_DIR/tasks.md with:
+   - Correct feature name from implementation plan
+   - Numbered tasks (T001, T002, etc.)
+   - Clear file paths for each task
+   - Dependency notes
+   - Parallel execution guidance
+
+Context for task generation: $ARGUMENTS
+
+The tasks.md should be immediately executable - each task must be specific enough that an LLM can complete it without additional context.
diff --git a/.cursor/rules/specify-rules.mdc b/.cursor/rules/specify-rules.mdc
new file mode 100644
index 0000000000..33a30db03c
--- /dev/null
+++ b/.cursor/rules/specify-rules.mdc
@@ -0,0 +1,25 @@
+# full-stack-fastapi-template Development Guidelines
+
+Auto-generated from all feature plans. Last updated: 2025-10-03
+
+## Active Technologies
+- Python 3.11+ + SQLModel, Mermaid, Git hooks, pre-commit framework (001-as-a-first)
+
+## Project Structure
+```
+backend/
+frontend/
+tests/
+```
+
+## Commands
+cd src [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] pytest [ONLY COMMANDS FOR ACTIVE TECHNOLOGIES][ONLY COMMANDS FOR ACTIVE TECHNOLOGIES] ruff check .
+
+## Code Style
+Python 3.11+: Follow standard conventions
+
+## Recent Changes
+- 001-as-a-first: Added Python 3.11+ + SQLModel, Mermaid, Git hooks, pre-commit framework
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->
\ No newline at end of file
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 37534e2ab0..c3d9959b6e 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -32,6 +32,17 @@ repos:
         language: system
         types: [text]
         files: ^frontend/
+      - id: erd-generation
+        name: ERD generation
+        entry: bash -c 'cd backend && python scripts/generate_erd.py --validate --verbose --force'
+        language: system
+        types: [python]
+        files: ^backend/app/.*\.py$
+        stages: [pre-commit]
+        always_run: false
+        pass_filenames: true
+        require_serial: false
+        description: "Generate and validate ERD diagrams from SQLModel definitions (Mermaid format)"
 
 ci:
   autofix_commit_msg: 🎨 [pre-commit.ci] Auto format from pre-commit.com hooks
diff --git a/.specify/memory/constitution.md b/.specify/memory/constitution.md
new file mode 100644
index 0000000000..b98e0efaeb
--- /dev/null
+++ b/.specify/memory/constitution.md
@@ -0,0 +1,102 @@
+<!-- 
+Sync Impact Report:
+Version change: 0.1.0 → 1.0.0 (MAJOR: Initial constitution creation)
+Modified principles: N/A (new constitution)
+Added sections: Development Workflow, Quality Standards, Security Requirements
+Removed sections: N/A (new constitution)
+Templates requiring updates:
+✅ plan-template.md - Constitution Check section aligns with new principles
+✅ spec-template.md - No changes needed, general template structure maintained
+✅ tasks-template.md - TDD principles align with constitution requirements
+Follow-up TODOs: None - all placeholders resolved
+-->
+
+# Full Stack FastAPI Template Constitution
+
+## Core Principles
+
+### I. Full-Stack Integration (NON-NEGOTIABLE)
+Every feature MUST be implemented across the entire stack - backend API, frontend UI, database schema, and tests. No feature is complete without end-to-end functionality. This ensures the template remains production-ready and demonstrates complete implementation patterns for users.
+
+### II. Test-Driven Development (NON-NEGOTIABLE)
+TDD is mandatory for all new features: Tests written → User approved → Tests fail → Then implement. Red-Green-Refactor cycle strictly enforced. All features MUST have unit tests, integration tests, and end-to-end tests before implementation begins.
+
+### III. Auto-Generated Client Consistency
+The frontend client MUST be automatically generated from backend OpenAPI schemas. Any API changes MUST trigger client regeneration. Manual API client modifications are forbidden to maintain consistency and prevent drift between backend and frontend.
+
+### IV. Docker-First Development
+All development and deployment MUST use Docker Compose. Local development MUST mirror production environment. Features MUST work in containerized environment before local development alternatives are considered.
+
+### V. Security by Default
+All new features MUST implement secure defaults: JWT authentication, password hashing, CORS configuration, input validation, and SQL injection prevention. Security considerations MUST be documented in feature specifications.
+
+## Development Workflow
+
+### Code Quality Standards
+- Pre-commit hooks MUST run before any commit (linting, formatting, type checking)
+- All Python code MUST pass Ruff linting and formatting checks
+- All TypeScript/JavaScript MUST pass ESLint and Prettier checks
+- Code coverage MUST maintain minimum thresholds (backend: 80%, frontend: 70%)
+
+### Testing Requirements
+- Unit tests MUST cover all business logic and utility functions
+- Integration tests MUST verify API endpoints and database interactions
+- End-to-end tests MUST validate complete user workflows
+- Contract tests MUST ensure API schema consistency
+- ERD generation MUST have unit tests, integration tests, and performance tests
+- ERD validation MUST include syntax validation and relationship verification
+
+### Documentation Standards
+- All new features MUST include API documentation via OpenAPI/Swagger
+- User-facing features MUST have updated README sections
+- Complex business logic MUST include inline documentation
+- Deployment changes MUST update deployment.md
+- Database schema changes MUST automatically update Entity Relationship Diagrams (ERD)
+- ERD documentation MUST be generated from SQLModel definitions and kept in sync
+
+## Quality Standards
+
+### Performance Requirements
+- API endpoints MUST respond within 200ms for 95th percentile
+- Frontend pages MUST load within 2 seconds
+- Database queries MUST be optimized and indexed appropriately
+- Docker containers MUST start within 30 seconds
+- ERD generation MUST complete within 30 seconds for schemas with up to 20 tables and 100 fields
+
+### Accessibility Standards
+- All UI components MUST meet WCAG 2.1 AA standards
+- Forms MUST have proper labels and validation messages
+- Navigation MUST be keyboard accessible
+- Color contrast MUST meet accessibility requirements
+
+## Security Requirements
+
+### Authentication & Authorization
+- JWT tokens MUST use secure secret keys (minimum 32 characters)
+- Password requirements MUST enforce complexity standards
+- Session management MUST implement proper expiration
+- Role-based access control MUST be implemented for admin features
+
+### Data Protection
+- All user input MUST be validated and sanitized
+- Database queries MUST use parameterized statements
+- Sensitive data MUST be encrypted at rest
+- API endpoints MUST implement rate limiting
+
+### Infrastructure Security
+- Docker images MUST use non-root users
+- Environment variables MUST be properly secured
+- HTTPS MUST be enforced in production
+- Secrets MUST NOT be committed to version control
+
+## Governance
+
+This constitution supersedes all other development practices and guidelines. Amendments require:
+1. Documentation of the proposed change and rationale
+2. Impact assessment on existing features and templates
+3. Approval through pull request review process
+4. Migration plan for any breaking changes
+
+All pull requests and code reviews MUST verify compliance with constitutional principles. Complexity additions MUST be justified with clear business value and technical necessity. Use development.md and deployment.md for runtime development guidance.
+
+**Version**: 1.0.0 | **Ratified**: 2024-12-19 | **Last Amended**: 2024-12-19
\ No newline at end of file
diff --git a/.specify/scripts/bash/check-prerequisites.sh b/.specify/scripts/bash/check-prerequisites.sh
new file mode 100755
index 0000000000..f32b6245ae
--- /dev/null
+++ b/.specify/scripts/bash/check-prerequisites.sh
@@ -0,0 +1,166 @@
+#!/usr/bin/env bash
+
+# Consolidated prerequisite checking script
+#
+# This script provides unified prerequisite checking for Spec-Driven Development workflow.
+# It replaces the functionality previously spread across multiple scripts.
+#
+# Usage: ./check-prerequisites.sh [OPTIONS]
+#
+# OPTIONS:
+#   --json              Output in JSON format
+#   --require-tasks     Require tasks.md to exist (for implementation phase)
+#   --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+#   --paths-only        Only output path variables (no validation)
+#   --help, -h          Show help message
+#
+# OUTPUTS:
+#   JSON mode: {"FEATURE_DIR":"...", "AVAILABLE_DOCS":["..."]}
+#   Text mode: FEATURE_DIR:... \n AVAILABLE_DOCS: \n ✓/✗ file.md
+#   Paths only: REPO_ROOT: ... \n BRANCH: ... \n FEATURE_DIR: ... etc.
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+REQUIRE_TASKS=false
+INCLUDE_TASKS=false
+PATHS_ONLY=false
+
+for arg in "$@"; do
+    case "$arg" in
+        --json)
+            JSON_MODE=true
+            ;;
+        --require-tasks)
+            REQUIRE_TASKS=true
+            ;;
+        --include-tasks)
+            INCLUDE_TASKS=true
+            ;;
+        --paths-only)
+            PATHS_ONLY=true
+            ;;
+        --help|-h)
+            cat << 'EOF'
+Usage: check-prerequisites.sh [OPTIONS]
+
+Consolidated prerequisite checking for Spec-Driven Development workflow.
+
+OPTIONS:
+  --json              Output in JSON format
+  --require-tasks     Require tasks.md to exist (for implementation phase)
+  --include-tasks     Include tasks.md in AVAILABLE_DOCS list
+  --paths-only        Only output path variables (no prerequisite validation)
+  --help, -h          Show this help message
+
+EXAMPLES:
+  # Check task prerequisites (plan.md required)
+  ./check-prerequisites.sh --json
+  
+  # Check implementation prerequisites (plan.md + tasks.md required)
+  ./check-prerequisites.sh --json --require-tasks --include-tasks
+  
+  # Get feature paths only (no validation)
+  ./check-prerequisites.sh --paths-only
+  
+EOF
+            exit 0
+            ;;
+        *)
+            echo "ERROR: Unknown option '$arg'. Use --help for usage information." >&2
+            exit 1
+            ;;
+    esac
+done
+
+# Source common functions
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get feature paths and validate branch
+eval $(get_feature_paths)
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
+# If paths-only mode, output paths and exit (support JSON + paths-only combined)
+if $PATHS_ONLY; then
+    if $JSON_MODE; then
+        # Minimal JSON paths payload (no validation performed)
+        printf '{"REPO_ROOT":"%s","BRANCH":"%s","FEATURE_DIR":"%s","FEATURE_SPEC":"%s","IMPL_PLAN":"%s","TASKS":"%s"}\n' \
+            "$REPO_ROOT" "$CURRENT_BRANCH" "$FEATURE_DIR" "$FEATURE_SPEC" "$IMPL_PLAN" "$TASKS"
+    else
+        echo "REPO_ROOT: $REPO_ROOT"
+        echo "BRANCH: $CURRENT_BRANCH"
+        echo "FEATURE_DIR: $FEATURE_DIR"
+        echo "FEATURE_SPEC: $FEATURE_SPEC"
+        echo "IMPL_PLAN: $IMPL_PLAN"
+        echo "TASKS: $TASKS"
+    fi
+    exit 0
+fi
+
+# Validate required directories and files
+if [[ ! -d "$FEATURE_DIR" ]]; then
+    echo "ERROR: Feature directory not found: $FEATURE_DIR" >&2
+    echo "Run /specify first to create the feature structure." >&2
+    exit 1
+fi
+
+if [[ ! -f "$IMPL_PLAN" ]]; then
+    echo "ERROR: plan.md not found in $FEATURE_DIR" >&2
+    echo "Run /plan first to create the implementation plan." >&2
+    exit 1
+fi
+
+# Check for tasks.md if required
+if $REQUIRE_TASKS && [[ ! -f "$TASKS" ]]; then
+    echo "ERROR: tasks.md not found in $FEATURE_DIR" >&2
+    echo "Run /tasks first to create the task list." >&2
+    exit 1
+fi
+
+# Build list of available documents
+docs=()
+
+# Always check these optional docs
+[[ -f "$RESEARCH" ]] && docs+=("research.md")
+[[ -f "$DATA_MODEL" ]] && docs+=("data-model.md")
+
+# Check contracts directory (only if it exists and has files)
+if [[ -d "$CONTRACTS_DIR" ]] && [[ -n "$(ls -A "$CONTRACTS_DIR" 2>/dev/null)" ]]; then
+    docs+=("contracts/")
+fi
+
+[[ -f "$QUICKSTART" ]] && docs+=("quickstart.md")
+
+# Include tasks.md if requested and it exists
+if $INCLUDE_TASKS && [[ -f "$TASKS" ]]; then
+    docs+=("tasks.md")
+fi
+
+# Output results
+if $JSON_MODE; then
+    # Build JSON array of documents
+    if [[ ${#docs[@]} -eq 0 ]]; then
+        json_docs="[]"
+    else
+        json_docs=$(printf '"%s",' "${docs[@]}")
+        json_docs="[${json_docs%,}]"
+    fi
+    
+    printf '{"FEATURE_DIR":"%s","AVAILABLE_DOCS":%s}\n' "$FEATURE_DIR" "$json_docs"
+else
+    # Text output
+    echo "FEATURE_DIR:$FEATURE_DIR"
+    echo "AVAILABLE_DOCS:"
+    
+    # Show status of each potential document
+    check_file "$RESEARCH" "research.md"
+    check_file "$DATA_MODEL" "data-model.md"
+    check_dir "$CONTRACTS_DIR" "contracts/"
+    check_file "$QUICKSTART" "quickstart.md"
+    
+    if $INCLUDE_TASKS; then
+        check_file "$TASKS" "tasks.md"
+    fi
+fi
\ No newline at end of file
diff --git a/.specify/scripts/bash/common.sh b/.specify/scripts/bash/common.sh
new file mode 100755
index 0000000000..34e5d4bb78
--- /dev/null
+++ b/.specify/scripts/bash/common.sh
@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+# Common functions and variables for all scripts
+
+# Get repository root, with fallback for non-git repositories
+get_repo_root() {
+    if git rev-parse --show-toplevel >/dev/null 2>&1; then
+        git rev-parse --show-toplevel
+    else
+        # Fall back to script location for non-git repos
+        local script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+        (cd "$script_dir/../../.." && pwd)
+    fi
+}
+
+# Get current branch, with fallback for non-git repositories
+get_current_branch() {
+    # First check if SPECIFY_FEATURE environment variable is set
+    if [[ -n "${SPECIFY_FEATURE:-}" ]]; then
+        echo "$SPECIFY_FEATURE"
+        return
+    fi
+    
+    # Then check git if available
+    if git rev-parse --abbrev-ref HEAD >/dev/null 2>&1; then
+        git rev-parse --abbrev-ref HEAD
+        return
+    fi
+    
+    # For non-git repos, try to find the latest feature directory
+    local repo_root=$(get_repo_root)
+    local specs_dir="$repo_root/specs"
+    
+    if [[ -d "$specs_dir" ]]; then
+        local latest_feature=""
+        local highest=0
+        
+        for dir in "$specs_dir"/*; do
+            if [[ -d "$dir" ]]; then
+                local dirname=$(basename "$dir")
+                if [[ "$dirname" =~ ^([0-9]{3})- ]]; then
+                    local number=${BASH_REMATCH[1]}
+                    number=$((10#$number))
+                    if [[ "$number" -gt "$highest" ]]; then
+                        highest=$number
+                        latest_feature=$dirname
+                    fi
+                fi
+            fi
+        done
+        
+        if [[ -n "$latest_feature" ]]; then
+            echo "$latest_feature"
+            return
+        fi
+    fi
+    
+    echo "main"  # Final fallback
+}
+
+# Check if we have git available
+has_git() {
+    git rev-parse --show-toplevel >/dev/null 2>&1
+}
+
+check_feature_branch() {
+    local branch="$1"
+    local has_git_repo="$2"
+    
+    # For non-git repos, we can't enforce branch naming but still provide output
+    if [[ "$has_git_repo" != "true" ]]; then
+        echo "[specify] Warning: Git repository not detected; skipped branch validation" >&2
+        return 0
+    fi
+    
+    if [[ ! "$branch" =~ ^[0-9]{3}- ]]; then
+        echo "ERROR: Not on a feature branch. Current branch: $branch" >&2
+        echo "Feature branches should be named like: 001-feature-name" >&2
+        return 1
+    fi
+    
+    return 0
+}
+
+get_feature_dir() { echo "$1/specs/$2"; }
+
+get_feature_paths() {
+    local repo_root=$(get_repo_root)
+    local current_branch=$(get_current_branch)
+    local has_git_repo="false"
+    
+    if has_git; then
+        has_git_repo="true"
+    fi
+    
+    local feature_dir=$(get_feature_dir "$repo_root" "$current_branch")
+    
+    cat <<EOF
+REPO_ROOT='$repo_root'
+CURRENT_BRANCH='$current_branch'
+HAS_GIT='$has_git_repo'
+FEATURE_DIR='$feature_dir'
+FEATURE_SPEC='$feature_dir/spec.md'
+IMPL_PLAN='$feature_dir/plan.md'
+TASKS='$feature_dir/tasks.md'
+RESEARCH='$feature_dir/research.md'
+DATA_MODEL='$feature_dir/data-model.md'
+QUICKSTART='$feature_dir/quickstart.md'
+CONTRACTS_DIR='$feature_dir/contracts'
+EOF
+}
+
+check_file() { [[ -f "$1" ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
+check_dir() { [[ -d "$1" && -n $(ls -A "$1" 2>/dev/null) ]] && echo "  ✓ $2" || echo "  ✗ $2"; }
diff --git a/.specify/scripts/bash/create-new-feature.sh b/.specify/scripts/bash/create-new-feature.sh
new file mode 100755
index 0000000000..5cb17fabef
--- /dev/null
+++ b/.specify/scripts/bash/create-new-feature.sh
@@ -0,0 +1,97 @@
+#!/usr/bin/env bash
+
+set -e
+
+JSON_MODE=false
+ARGS=()
+for arg in "$@"; do
+    case "$arg" in
+        --json) JSON_MODE=true ;;
+        --help|-h) echo "Usage: $0 [--json] <feature_description>"; exit 0 ;;
+        *) ARGS+=("$arg") ;;
+    esac
+done
+
+FEATURE_DESCRIPTION="${ARGS[*]}"
+if [ -z "$FEATURE_DESCRIPTION" ]; then
+    echo "Usage: $0 [--json] <feature_description>" >&2
+    exit 1
+fi
+
+# Function to find the repository root by searching for existing project markers
+find_repo_root() {
+    local dir="$1"
+    while [ "$dir" != "/" ]; do
+        if [ -d "$dir/.git" ] || [ -d "$dir/.specify" ]; then
+            echo "$dir"
+            return 0
+        fi
+        dir="$(dirname "$dir")"
+    done
+    return 1
+}
+
+# Resolve repository root. Prefer git information when available, but fall back
+# to searching for repository markers so the workflow still functions in repositories that
+# were initialised with --no-git.
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+if git rev-parse --show-toplevel >/dev/null 2>&1; then
+    REPO_ROOT=$(git rev-parse --show-toplevel)
+    HAS_GIT=true
+else
+    REPO_ROOT="$(find_repo_root "$SCRIPT_DIR")"
+    if [ -z "$REPO_ROOT" ]; then
+        echo "Error: Could not determine repository root. Please run this script from within the repository." >&2
+        exit 1
+    fi
+    HAS_GIT=false
+fi
+
+cd "$REPO_ROOT"
+
+SPECS_DIR="$REPO_ROOT/specs"
+mkdir -p "$SPECS_DIR"
+
+HIGHEST=0
+if [ -d "$SPECS_DIR" ]; then
+    for dir in "$SPECS_DIR"/*; do
+        [ -d "$dir" ] || continue
+        dirname=$(basename "$dir")
+        number=$(echo "$dirname" | grep -o '^[0-9]\+' || echo "0")
+        number=$((10#$number))
+        if [ "$number" -gt "$HIGHEST" ]; then HIGHEST=$number; fi
+    done
+fi
+
+NEXT=$((HIGHEST + 1))
+FEATURE_NUM=$(printf "%03d" "$NEXT")
+
+BRANCH_NAME=$(echo "$FEATURE_DESCRIPTION" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/-\+/-/g' | sed 's/^-//' | sed 's/-$//')
+WORDS=$(echo "$BRANCH_NAME" | tr '-' '\n' | grep -v '^$' | head -3 | tr '\n' '-' | sed 's/-$//')
+BRANCH_NAME="${FEATURE_NUM}-${WORDS}"
+
+if [ "$HAS_GIT" = true ]; then
+    git checkout -b "$BRANCH_NAME"
+else
+    >&2 echo "[specify] Warning: Git repository not detected; skipped branch creation for $BRANCH_NAME"
+fi
+
+FEATURE_DIR="$SPECS_DIR/$BRANCH_NAME"
+mkdir -p "$FEATURE_DIR"
+
+TEMPLATE="$REPO_ROOT/.specify/templates/spec-template.md"
+SPEC_FILE="$FEATURE_DIR/spec.md"
+if [ -f "$TEMPLATE" ]; then cp "$TEMPLATE" "$SPEC_FILE"; else touch "$SPEC_FILE"; fi
+
+# Set the SPECIFY_FEATURE environment variable for the current session
+export SPECIFY_FEATURE="$BRANCH_NAME"
+
+if $JSON_MODE; then
+    printf '{"BRANCH_NAME":"%s","SPEC_FILE":"%s","FEATURE_NUM":"%s"}\n' "$BRANCH_NAME" "$SPEC_FILE" "$FEATURE_NUM"
+else
+    echo "BRANCH_NAME: $BRANCH_NAME"
+    echo "SPEC_FILE: $SPEC_FILE"
+    echo "FEATURE_NUM: $FEATURE_NUM"
+    echo "SPECIFY_FEATURE environment variable set to: $BRANCH_NAME"
+fi
diff --git a/.specify/scripts/bash/setup-plan.sh b/.specify/scripts/bash/setup-plan.sh
new file mode 100755
index 0000000000..654ba50d7b
--- /dev/null
+++ b/.specify/scripts/bash/setup-plan.sh
@@ -0,0 +1,60 @@
+#!/usr/bin/env bash
+
+set -e
+
+# Parse command line arguments
+JSON_MODE=false
+ARGS=()
+
+for arg in "$@"; do
+    case "$arg" in
+        --json) 
+            JSON_MODE=true 
+            ;;
+        --help|-h) 
+            echo "Usage: $0 [--json]"
+            echo "  --json    Output results in JSON format"
+            echo "  --help    Show this help message"
+            exit 0 
+            ;;
+        *) 
+            ARGS+=("$arg") 
+            ;;
+    esac
+done
+
+# Get script directory and load common functions
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get all paths and variables from common functions
+eval $(get_feature_paths)
+
+# Check if we're on a proper feature branch (only for git repos)
+check_feature_branch "$CURRENT_BRANCH" "$HAS_GIT" || exit 1
+
+# Ensure the feature directory exists
+mkdir -p "$FEATURE_DIR"
+
+# Copy plan template if it exists
+TEMPLATE="$REPO_ROOT/.specify/templates/plan-template.md"
+if [[ -f "$TEMPLATE" ]]; then
+    cp "$TEMPLATE" "$IMPL_PLAN"
+    echo "Copied plan template to $IMPL_PLAN"
+else
+    echo "Warning: Plan template not found at $TEMPLATE"
+    # Create a basic plan file if template doesn't exist
+    touch "$IMPL_PLAN"
+fi
+
+# Output results
+if $JSON_MODE; then
+    printf '{"FEATURE_SPEC":"%s","IMPL_PLAN":"%s","SPECS_DIR":"%s","BRANCH":"%s","HAS_GIT":"%s"}\n' \
+        "$FEATURE_SPEC" "$IMPL_PLAN" "$FEATURE_DIR" "$CURRENT_BRANCH" "$HAS_GIT"
+else
+    echo "FEATURE_SPEC: $FEATURE_SPEC"
+    echo "IMPL_PLAN: $IMPL_PLAN" 
+    echo "SPECS_DIR: $FEATURE_DIR"
+    echo "BRANCH: $CURRENT_BRANCH"
+    echo "HAS_GIT: $HAS_GIT"
+fi
diff --git a/.specify/scripts/bash/update-agent-context.sh b/.specify/scripts/bash/update-agent-context.sh
new file mode 100755
index 0000000000..d3cc422ed2
--- /dev/null
+++ b/.specify/scripts/bash/update-agent-context.sh
@@ -0,0 +1,719 @@
+#!/usr/bin/env bash
+
+# Update agent context files with information from plan.md
+#
+# This script maintains AI agent context files by parsing feature specifications 
+# and updating agent-specific configuration files with project information.
+#
+# MAIN FUNCTIONS:
+# 1. Environment Validation
+#    - Verifies git repository structure and branch information
+#    - Checks for required plan.md files and templates
+#    - Validates file permissions and accessibility
+#
+# 2. Plan Data Extraction
+#    - Parses plan.md files to extract project metadata
+#    - Identifies language/version, frameworks, databases, and project types
+#    - Handles missing or incomplete specification data gracefully
+#
+# 3. Agent File Management
+#    - Creates new agent context files from templates when needed
+#    - Updates existing agent files with new project information
+#    - Preserves manual additions and custom configurations
+#    - Supports multiple AI agent formats and directory structures
+#
+# 4. Content Generation
+#    - Generates language-specific build/test commands
+#    - Creates appropriate project directory structures
+#    - Updates technology stacks and recent changes sections
+#    - Maintains consistent formatting and timestamps
+#
+# 5. Multi-Agent Support
+#    - Handles agent-specific file paths and naming conventions
+#    - Supports: Claude, Gemini, Copilot, Cursor, Qwen, opencode, Codex, Windsurf
+#    - Can update single agents or all existing agent files
+#    - Creates default Claude file if no agent files exist
+#
+# Usage: ./update-agent-context.sh [agent_type]
+# Agent types: claude|gemini|copilot|cursor|qwen|opencode|codex|windsurf
+# Leave empty to update all existing agent files
+
+set -e
+
+# Enable strict error handling
+set -u
+set -o pipefail
+
+#==============================================================================
+# Configuration and Global Variables
+#==============================================================================
+
+# Get script directory and load common functions
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$SCRIPT_DIR/common.sh"
+
+# Get all paths and variables from common functions
+eval $(get_feature_paths)
+
+NEW_PLAN="$IMPL_PLAN"  # Alias for compatibility with existing code
+AGENT_TYPE="${1:-}"
+
+# Agent-specific file paths  
+CLAUDE_FILE="$REPO_ROOT/CLAUDE.md"
+GEMINI_FILE="$REPO_ROOT/GEMINI.md"
+COPILOT_FILE="$REPO_ROOT/.github/copilot-instructions.md"
+CURSOR_FILE="$REPO_ROOT/.cursor/rules/specify-rules.mdc"
+QWEN_FILE="$REPO_ROOT/QWEN.md"
+AGENTS_FILE="$REPO_ROOT/AGENTS.md"
+WINDSURF_FILE="$REPO_ROOT/.windsurf/rules/specify-rules.md"
+KILOCODE_FILE="$REPO_ROOT/.kilocode/rules/specify-rules.md"
+AUGGIE_FILE="$REPO_ROOT/.augment/rules/specify-rules.md"
+ROO_FILE="$REPO_ROOT/.roo/rules/specify-rules.md"
+
+# Template file
+TEMPLATE_FILE="$REPO_ROOT/.specify/templates/agent-file-template.md"
+
+# Global variables for parsed plan data
+NEW_LANG=""
+NEW_FRAMEWORK=""
+NEW_DB=""
+NEW_PROJECT_TYPE=""
+
+#==============================================================================
+# Utility Functions
+#==============================================================================
+
+log_info() {
+    echo "INFO: $1"
+}
+
+log_success() {
+    echo "✓ $1"
+}
+
+log_error() {
+    echo "ERROR: $1" >&2
+}
+
+log_warning() {
+    echo "WARNING: $1" >&2
+}
+
+# Cleanup function for temporary files
+cleanup() {
+    local exit_code=$?
+    rm -f /tmp/agent_update_*_$$
+    rm -f /tmp/manual_additions_$$
+    exit $exit_code
+}
+
+# Set up cleanup trap
+trap cleanup EXIT INT TERM
+
+#==============================================================================
+# Validation Functions
+#==============================================================================
+
+validate_environment() {
+    # Check if we have a current branch/feature (git or non-git)
+    if [[ -z "$CURRENT_BRANCH" ]]; then
+        log_error "Unable to determine current feature"
+        if [[ "$HAS_GIT" == "true" ]]; then
+            log_info "Make sure you're on a feature branch"
+        else
+            log_info "Set SPECIFY_FEATURE environment variable or create a feature first"
+        fi
+        exit 1
+    fi
+    
+    # Check if plan.md exists
+    if [[ ! -f "$NEW_PLAN" ]]; then
+        log_error "No plan.md found at $NEW_PLAN"
+        log_info "Make sure you're working on a feature with a corresponding spec directory"
+        if [[ "$HAS_GIT" != "true" ]]; then
+            log_info "Use: export SPECIFY_FEATURE=your-feature-name or create a new feature first"
+        fi
+        exit 1
+    fi
+    
+    # Check if template exists (needed for new files)
+    if [[ ! -f "$TEMPLATE_FILE" ]]; then
+        log_warning "Template file not found at $TEMPLATE_FILE"
+        log_warning "Creating new agent files will fail"
+    fi
+}
+
+#==============================================================================
+# Plan Parsing Functions
+#==============================================================================
+
+extract_plan_field() {
+    local field_pattern="$1"
+    local plan_file="$2"
+    
+    grep "^\*\*${field_pattern}\*\*: " "$plan_file" 2>/dev/null | \
+        head -1 | \
+        sed "s|^\*\*${field_pattern}\*\*: ||" | \
+        sed 's/^[ \t]*//;s/[ \t]*$//' | \
+        grep -v "NEEDS CLARIFICATION" | \
+        grep -v "^N/A$" || echo ""
+}
+
+parse_plan_data() {
+    local plan_file="$1"
+    
+    if [[ ! -f "$plan_file" ]]; then
+        log_error "Plan file not found: $plan_file"
+        return 1
+    fi
+    
+    if [[ ! -r "$plan_file" ]]; then
+        log_error "Plan file is not readable: $plan_file"
+        return 1
+    fi
+    
+    log_info "Parsing plan data from $plan_file"
+    
+    NEW_LANG=$(extract_plan_field "Language/Version" "$plan_file")
+    NEW_FRAMEWORK=$(extract_plan_field "Primary Dependencies" "$plan_file")
+    NEW_DB=$(extract_plan_field "Storage" "$plan_file")
+    NEW_PROJECT_TYPE=$(extract_plan_field "Project Type" "$plan_file")
+    
+    # Log what we found
+    if [[ -n "$NEW_LANG" ]]; then
+        log_info "Found language: $NEW_LANG"
+    else
+        log_warning "No language information found in plan"
+    fi
+    
+    if [[ -n "$NEW_FRAMEWORK" ]]; then
+        log_info "Found framework: $NEW_FRAMEWORK"
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
+        log_info "Found database: $NEW_DB"
+    fi
+    
+    if [[ -n "$NEW_PROJECT_TYPE" ]]; then
+        log_info "Found project type: $NEW_PROJECT_TYPE"
+    fi
+}
+
+format_technology_stack() {
+    local lang="$1"
+    local framework="$2"
+    local parts=()
+    
+    # Add non-empty parts
+    [[ -n "$lang" && "$lang" != "NEEDS CLARIFICATION" ]] && parts+=("$lang")
+    [[ -n "$framework" && "$framework" != "NEEDS CLARIFICATION" && "$framework" != "N/A" ]] && parts+=("$framework")
+    
+    # Join with proper formatting
+    if [[ ${#parts[@]} -eq 0 ]]; then
+        echo ""
+    elif [[ ${#parts[@]} -eq 1 ]]; then
+        echo "${parts[0]}"
+    else
+        # Join multiple parts with " + "
+        local result="${parts[0]}"
+        for ((i=1; i<${#parts[@]}; i++)); do
+            result="$result + ${parts[i]}"
+        done
+        echo "$result"
+    fi
+}
+
+#==============================================================================
+# Template and Content Generation Functions
+#==============================================================================
+
+get_project_structure() {
+    local project_type="$1"
+    
+    if [[ "$project_type" == *"web"* ]]; then
+        echo "backend/\\nfrontend/\\ntests/"
+    else
+        echo "src/\\ntests/"
+    fi
+}
+
+get_commands_for_language() {
+    local lang="$1"
+    
+    case "$lang" in
+        *"Python"*)
+            echo "cd src && pytest && ruff check ."
+            ;;
+        *"Rust"*)
+            echo "cargo test && cargo clippy"
+            ;;
+        *"JavaScript"*|*"TypeScript"*)
+            echo "npm test && npm run lint"
+            ;;
+        *)
+            echo "# Add commands for $lang"
+            ;;
+    esac
+}
+
+get_language_conventions() {
+    local lang="$1"
+    echo "$lang: Follow standard conventions"
+}
+
+create_new_agent_file() {
+    local target_file="$1"
+    local temp_file="$2"
+    local project_name="$3"
+    local current_date="$4"
+    
+    if [[ ! -f "$TEMPLATE_FILE" ]]; then
+        log_error "Template not found at $TEMPLATE_FILE"
+        return 1
+    fi
+    
+    if [[ ! -r "$TEMPLATE_FILE" ]]; then
+        log_error "Template file is not readable: $TEMPLATE_FILE"
+        return 1
+    fi
+    
+    log_info "Creating new agent context file from template..."
+    
+    if ! cp "$TEMPLATE_FILE" "$temp_file"; then
+        log_error "Failed to copy template file"
+        return 1
+    fi
+    
+    # Replace template placeholders
+    local project_structure
+    project_structure=$(get_project_structure "$NEW_PROJECT_TYPE")
+    
+    local commands
+    commands=$(get_commands_for_language "$NEW_LANG")
+    
+    local language_conventions
+    language_conventions=$(get_language_conventions "$NEW_LANG")
+    
+    # Perform substitutions with error checking using safer approach
+    # Escape special characters for sed by using a different delimiter or escaping
+    local escaped_lang=$(printf '%s\n' "$NEW_LANG" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    local escaped_framework=$(printf '%s\n' "$NEW_FRAMEWORK" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    local escaped_branch=$(printf '%s\n' "$CURRENT_BRANCH" | sed 's/[\[\.*^$()+{}|]/\\&/g')
+    
+    # Build technology stack and recent change strings conditionally
+    local tech_stack
+    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
+        tech_stack="- $escaped_lang + $escaped_framework ($escaped_branch)"
+    elif [[ -n "$escaped_lang" ]]; then
+        tech_stack="- $escaped_lang ($escaped_branch)"
+    elif [[ -n "$escaped_framework" ]]; then
+        tech_stack="- $escaped_framework ($escaped_branch)"
+    else
+        tech_stack="- ($escaped_branch)"
+    fi
+
+    local recent_change
+    if [[ -n "$escaped_lang" && -n "$escaped_framework" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_lang + $escaped_framework"
+    elif [[ -n "$escaped_lang" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_lang"
+    elif [[ -n "$escaped_framework" ]]; then
+        recent_change="- $escaped_branch: Added $escaped_framework"
+    else
+        recent_change="- $escaped_branch: Added"
+    fi
+
+    local substitutions=(
+        "s|\[PROJECT NAME\]|$project_name|"
+        "s|\[DATE\]|$current_date|"
+        "s|\[EXTRACTED FROM ALL PLAN.MD FILES\]|$tech_stack|"
+        "s|\[ACTUAL STRUCTURE FROM PLANS\]|$project_structure|g"
+        "s|\[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES\]|$commands|"
+        "s|\[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE\]|$language_conventions|"
+        "s|\[LAST 3 FEATURES AND WHAT THEY ADDED\]|$recent_change|"
+    )
+    
+    for substitution in "${substitutions[@]}"; do
+        if ! sed -i.bak -e "$substitution" "$temp_file"; then
+            log_error "Failed to perform substitution: $substitution"
+            rm -f "$temp_file" "$temp_file.bak"
+            return 1
+        fi
+    done
+    
+    # Convert \n sequences to actual newlines
+    newline=$(printf '\n')
+    sed -i.bak2 "s/\\\\n/${newline}/g" "$temp_file"
+    
+    # Clean up backup files
+    rm -f "$temp_file.bak" "$temp_file.bak2"
+    
+    return 0
+}
+
+
+
+
+update_existing_agent_file() {
+    local target_file="$1"
+    local current_date="$2"
+    
+    log_info "Updating existing agent context file..."
+    
+    # Use a single temporary file for atomic update
+    local temp_file
+    temp_file=$(mktemp) || {
+        log_error "Failed to create temporary file"
+        return 1
+    }
+    
+    # Process the file in one pass
+    local tech_stack=$(format_technology_stack "$NEW_LANG" "$NEW_FRAMEWORK")
+    local new_tech_entries=()
+    local new_change_entry=""
+    
+    # Prepare new technology entries
+    if [[ -n "$tech_stack" ]] && ! grep -q "$tech_stack" "$target_file"; then
+        new_tech_entries+=("- $tech_stack ($CURRENT_BRANCH)")
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]] && ! grep -q "$NEW_DB" "$target_file"; then
+        new_tech_entries+=("- $NEW_DB ($CURRENT_BRANCH)")
+    fi
+    
+    # Prepare new change entry
+    if [[ -n "$tech_stack" ]]; then
+        new_change_entry="- $CURRENT_BRANCH: Added $tech_stack"
+    elif [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]] && [[ "$NEW_DB" != "NEEDS CLARIFICATION" ]]; then
+        new_change_entry="- $CURRENT_BRANCH: Added $NEW_DB"
+    fi
+    
+    # Process file line by line
+    local in_tech_section=false
+    local in_changes_section=false
+    local tech_entries_added=false
+    local changes_entries_added=false
+    local existing_changes_count=0
+    
+    while IFS= read -r line || [[ -n "$line" ]]; do
+        # Handle Active Technologies section
+        if [[ "$line" == "## Active Technologies" ]]; then
+            echo "$line" >> "$temp_file"
+            in_tech_section=true
+            continue
+        elif [[ $in_tech_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
+            # Add new tech entries before closing the section
+            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+                tech_entries_added=true
+            fi
+            echo "$line" >> "$temp_file"
+            in_tech_section=false
+            continue
+        elif [[ $in_tech_section == true ]] && [[ -z "$line" ]]; then
+            # Add new tech entries before empty line in tech section
+            if [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+                printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+                tech_entries_added=true
+            fi
+            echo "$line" >> "$temp_file"
+            continue
+        fi
+        
+        # Handle Recent Changes section
+        if [[ "$line" == "## Recent Changes" ]]; then
+            echo "$line" >> "$temp_file"
+            # Add new change entry right after the heading
+            if [[ -n "$new_change_entry" ]]; then
+                echo "$new_change_entry" >> "$temp_file"
+            fi
+            in_changes_section=true
+            changes_entries_added=true
+            continue
+        elif [[ $in_changes_section == true ]] && [[ "$line" =~ ^##[[:space:]] ]]; then
+            echo "$line" >> "$temp_file"
+            in_changes_section=false
+            continue
+        elif [[ $in_changes_section == true ]] && [[ "$line" == "- "* ]]; then
+            # Keep only first 2 existing changes
+            if [[ $existing_changes_count -lt 2 ]]; then
+                echo "$line" >> "$temp_file"
+                ((existing_changes_count++))
+            fi
+            continue
+        fi
+        
+        # Update timestamp
+        if [[ "$line" =~ \*\*Last\ updated\*\*:.*[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9] ]]; then
+            echo "$line" | sed "s/[0-9][0-9][0-9][0-9]-[0-9][0-9]-[0-9][0-9]/$current_date/" >> "$temp_file"
+        else
+            echo "$line" >> "$temp_file"
+        fi
+    done < "$target_file"
+    
+    # Post-loop check: if we're still in the Active Technologies section and haven't added new entries
+    if [[ $in_tech_section == true ]] && [[ $tech_entries_added == false ]] && [[ ${#new_tech_entries[@]} -gt 0 ]]; then
+        printf '%s\n' "${new_tech_entries[@]}" >> "$temp_file"
+    fi
+    
+    # Move temp file to target atomically
+    if ! mv "$temp_file" "$target_file"; then
+        log_error "Failed to update target file"
+        rm -f "$temp_file"
+        return 1
+    fi
+    
+    return 0
+}
+#==============================================================================
+# Main Agent File Update Function
+#==============================================================================
+
+update_agent_file() {
+    local target_file="$1"
+    local agent_name="$2"
+    
+    if [[ -z "$target_file" ]] || [[ -z "$agent_name" ]]; then
+        log_error "update_agent_file requires target_file and agent_name parameters"
+        return 1
+    fi
+    
+    log_info "Updating $agent_name context file: $target_file"
+    
+    local project_name
+    project_name=$(basename "$REPO_ROOT")
+    local current_date
+    current_date=$(date +%Y-%m-%d)
+    
+    # Create directory if it doesn't exist
+    local target_dir
+    target_dir=$(dirname "$target_file")
+    if [[ ! -d "$target_dir" ]]; then
+        if ! mkdir -p "$target_dir"; then
+            log_error "Failed to create directory: $target_dir"
+            return 1
+        fi
+    fi
+    
+    if [[ ! -f "$target_file" ]]; then
+        # Create new file from template
+        local temp_file
+        temp_file=$(mktemp) || {
+            log_error "Failed to create temporary file"
+            return 1
+        }
+        
+        if create_new_agent_file "$target_file" "$temp_file" "$project_name" "$current_date"; then
+            if mv "$temp_file" "$target_file"; then
+                log_success "Created new $agent_name context file"
+            else
+                log_error "Failed to move temporary file to $target_file"
+                rm -f "$temp_file"
+                return 1
+            fi
+        else
+            log_error "Failed to create new agent file"
+            rm -f "$temp_file"
+            return 1
+        fi
+    else
+        # Update existing file
+        if [[ ! -r "$target_file" ]]; then
+            log_error "Cannot read existing file: $target_file"
+            return 1
+        fi
+        
+        if [[ ! -w "$target_file" ]]; then
+            log_error "Cannot write to existing file: $target_file"
+            return 1
+        fi
+        
+        if update_existing_agent_file "$target_file" "$current_date"; then
+            log_success "Updated existing $agent_name context file"
+        else
+            log_error "Failed to update existing agent file"
+            return 1
+        fi
+    fi
+    
+    return 0
+}
+
+#==============================================================================
+# Agent Selection and Processing
+#==============================================================================
+
+update_specific_agent() {
+    local agent_type="$1"
+    
+    case "$agent_type" in
+        claude)
+            update_agent_file "$CLAUDE_FILE" "Claude Code"
+            ;;
+        gemini)
+            update_agent_file "$GEMINI_FILE" "Gemini CLI"
+            ;;
+        copilot)
+            update_agent_file "$COPILOT_FILE" "GitHub Copilot"
+            ;;
+        cursor)
+            update_agent_file "$CURSOR_FILE" "Cursor IDE"
+            ;;
+        qwen)
+            update_agent_file "$QWEN_FILE" "Qwen Code"
+            ;;
+        opencode)
+            update_agent_file "$AGENTS_FILE" "opencode"
+            ;;
+        codex)
+            update_agent_file "$AGENTS_FILE" "Codex CLI"
+            ;;
+        windsurf)
+            update_agent_file "$WINDSURF_FILE" "Windsurf"
+            ;;
+        kilocode)
+            update_agent_file "$KILOCODE_FILE" "Kilo Code"
+            ;;
+        auggie)
+            update_agent_file "$AUGGIE_FILE" "Auggie CLI"
+            ;;
+        roo)
+            update_agent_file "$ROO_FILE" "Roo Code"
+            ;;
+        *)
+            log_error "Unknown agent type '$agent_type'"
+            log_error "Expected: claude|gemini|copilot|cursor|qwen|opencode|codex|windsurf|kilocode|auggie|roo"
+            exit 1
+            ;;
+    esac
+}
+
+update_all_existing_agents() {
+    local found_agent=false
+    
+    # Check each possible agent file and update if it exists
+    if [[ -f "$CLAUDE_FILE" ]]; then
+        update_agent_file "$CLAUDE_FILE" "Claude Code"
+        found_agent=true
+    fi
+    
+    if [[ -f "$GEMINI_FILE" ]]; then
+        update_agent_file "$GEMINI_FILE" "Gemini CLI"
+        found_agent=true
+    fi
+    
+    if [[ -f "$COPILOT_FILE" ]]; then
+        update_agent_file "$COPILOT_FILE" "GitHub Copilot"
+        found_agent=true
+    fi
+    
+    if [[ -f "$CURSOR_FILE" ]]; then
+        update_agent_file "$CURSOR_FILE" "Cursor IDE"
+        found_agent=true
+    fi
+    
+    if [[ -f "$QWEN_FILE" ]]; then
+        update_agent_file "$QWEN_FILE" "Qwen Code"
+        found_agent=true
+    fi
+    
+    if [[ -f "$AGENTS_FILE" ]]; then
+        update_agent_file "$AGENTS_FILE" "Codex/opencode"
+        found_agent=true
+    fi
+    
+    if [[ -f "$WINDSURF_FILE" ]]; then
+        update_agent_file "$WINDSURF_FILE" "Windsurf"
+        found_agent=true
+    fi
+    
+    if [[ -f "$KILOCODE_FILE" ]]; then
+        update_agent_file "$KILOCODE_FILE" "Kilo Code"
+        found_agent=true
+    fi
+
+    if [[ -f "$AUGGIE_FILE" ]]; then
+        update_agent_file "$AUGGIE_FILE" "Auggie CLI"
+        found_agent=true
+    fi
+    
+    if [[ -f "$ROO_FILE" ]]; then
+        update_agent_file "$ROO_FILE" "Roo Code"
+        found_agent=true
+    fi
+    
+    # If no agent files exist, create a default Claude file
+    if [[ "$found_agent" == false ]]; then
+        log_info "No existing agent files found, creating default Claude file..."
+        update_agent_file "$CLAUDE_FILE" "Claude Code"
+    fi
+}
+print_summary() {
+    echo
+    log_info "Summary of changes:"
+    
+    if [[ -n "$NEW_LANG" ]]; then
+        echo "  - Added language: $NEW_LANG"
+    fi
+    
+    if [[ -n "$NEW_FRAMEWORK" ]]; then
+        echo "  - Added framework: $NEW_FRAMEWORK"
+    fi
+    
+    if [[ -n "$NEW_DB" ]] && [[ "$NEW_DB" != "N/A" ]]; then
+        echo "  - Added database: $NEW_DB"
+    fi
+    
+    echo
+    log_info "Usage: $0 [claude|gemini|copilot|cursor|qwen|opencode|codex|windsurf|kilocode|auggie|roo]"
+}
+
+#==============================================================================
+# Main Execution
+#==============================================================================
+
+main() {
+    # Validate environment before proceeding
+    validate_environment
+    
+    log_info "=== Updating agent context files for feature $CURRENT_BRANCH ==="
+    
+    # Parse the plan file to extract project information
+    if ! parse_plan_data "$NEW_PLAN"; then
+        log_error "Failed to parse plan data"
+        exit 1
+    fi
+    
+    # Process based on agent type argument
+    local success=true
+    
+    if [[ -z "$AGENT_TYPE" ]]; then
+        # No specific agent provided - update all existing agent files
+        log_info "No agent specified, updating all existing agent files..."
+        if ! update_all_existing_agents; then
+            success=false
+        fi
+    else
+        # Specific agent provided - update only that agent
+        log_info "Updating specific agent: $AGENT_TYPE"
+        if ! update_specific_agent "$AGENT_TYPE"; then
+            success=false
+        fi
+    fi
+    
+    # Print summary
+    print_summary
+    
+    if [[ "$success" == true ]]; then
+        log_success "Agent context update completed successfully"
+        exit 0
+    else
+        log_error "Agent context update completed with errors"
+        exit 1
+    fi
+}
+
+# Execute main function if script is run directly
+if [[ "${BASH_SOURCE[0]}" == "${0}" ]]; then
+    main "$@"
+fi
diff --git a/.specify/templates/agent-file-template.md b/.specify/templates/agent-file-template.md
new file mode 100644
index 0000000000..2301e0eaa2
--- /dev/null
+++ b/.specify/templates/agent-file-template.md
@@ -0,0 +1,23 @@
+# [PROJECT NAME] Development Guidelines
+
+Auto-generated from all feature plans. Last updated: [DATE]
+
+## Active Technologies
+[EXTRACTED FROM ALL PLAN.MD FILES]
+
+## Project Structure
+```
+[ACTUAL STRUCTURE FROM PLANS]
+```
+
+## Commands
+[ONLY COMMANDS FOR ACTIVE TECHNOLOGIES]
+
+## Code Style
+[LANGUAGE-SPECIFIC, ONLY FOR LANGUAGES IN USE]
+
+## Recent Changes
+[LAST 3 FEATURES AND WHAT THEY ADDED]
+
+<!-- MANUAL ADDITIONS START -->
+<!-- MANUAL ADDITIONS END -->
\ No newline at end of file
diff --git a/.specify/templates/plan-template.md b/.specify/templates/plan-template.md
new file mode 100644
index 0000000000..fe8cb9f9e1
--- /dev/null
+++ b/.specify/templates/plan-template.md
@@ -0,0 +1,224 @@
+
+# Implementation Plan: [FEATURE]
+
+**Branch**: `[###-feature-name]` | **Date**: [DATE] | **Spec**: [link]
+**Input**: Feature specification from `/specs/[###-feature-name]/spec.md`
+
+## Execution Flow (/plan command scope)
+```
+1. Load feature spec from Input path
+   → If not found: ERROR "No feature spec at {path}"
+2. Fill Technical Context (scan for NEEDS CLARIFICATION)
+   → Detect Project Type from file system structure or context (web=frontend+backend, mobile=app+api)
+   → Set Structure Decision based on project type
+3. Fill the Constitution Check section based on the content of the constitution document.
+4. Evaluate Constitution Check section below
+   → If violations exist: Document in Complexity Tracking
+   → If no justification possible: ERROR "Simplify approach first"
+   → Update Progress Tracking: Initial Constitution Check
+5. Execute Phase 0 → research.md
+   → If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
+6. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, `GEMINI.md` for Gemini CLI, `QWEN.md` for Qwen Code or `AGENTS.md` for opencode).
+7. Re-evaluate Constitution Check section
+   → If new violations: Refactor design, return to Phase 1
+   → Update Progress Tracking: Post-Design Constitution Check
+8. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md)
+9. STOP - Ready for /tasks command
+```
+
+**IMPORTANT**: The /plan command STOPS at step 7. Phases 2-4 are executed by other commands:
+- Phase 2: /tasks command creates tasks.md
+- Phase 3-4: Implementation execution (manual or via tools)
+
+## Summary
+[Extract from feature spec: primary requirement + technical approach from research]
+
+## Technical Context
+**Language/Version**: [e.g., Python 3.11, Swift 5.9, Rust 1.75 or NEEDS CLARIFICATION]  
+**Primary Dependencies**: [e.g., FastAPI, UIKit, LLVM or NEEDS CLARIFICATION]  
+**Storage**: [if applicable, e.g., PostgreSQL, CoreData, files or N/A]  
+**Testing**: [e.g., pytest, XCTest, cargo test or NEEDS CLARIFICATION]  
+**Target Platform**: [e.g., Linux server, iOS 15+, WASM or NEEDS CLARIFICATION]
+**Project Type**: [single/web/mobile - determines source structure]  
+**Performance Goals**: [domain-specific, e.g., 1000 req/s, 10k lines/sec, 60 fps or NEEDS CLARIFICATION]  
+**Constraints**: [domain-specific, e.g., <200ms p95, <100MB memory, offline-capable or NEEDS CLARIFICATION]  
+**Scale/Scope**: [domain-specific, e.g., 10k users, 1M LOC, 50 screens or NEEDS CLARIFICATION]
+
+## Constitution Check
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+**Full-Stack Integration**: Does this feature require backend API, frontend UI, database changes, and tests?
+**Test-Driven Development**: Are test scenarios defined before implementation planning?
+**Auto-Generated Client**: Will API changes require frontend client regeneration?
+**Docker-First**: Does the feature work in containerized environment?
+**Security by Default**: Are authentication, validation, and security considerations included?
+**ERD Documentation**: Will database schema changes require ERD updates and validation?
+
+## Project Structure
+
+### Documentation (this feature)
+```
+specs/[###-feature]/
+├── plan.md              # This file (/plan command output)
+├── research.md          # Phase 0 output (/plan command)
+├── data-model.md        # Phase 1 output (/plan command)
+├── quickstart.md        # Phase 1 output (/plan command)
+├── contracts/           # Phase 1 output (/plan command)
+└── tasks.md             # Phase 2 output (/tasks command - NOT created by /plan)
+```
+
+### Source Code (repository root)
+<!--
+  ACTION REQUIRED: Replace the placeholder tree below with the concrete layout
+  for this feature. Delete unused options and expand the chosen structure with
+  real paths (e.g., apps/admin, packages/something). The delivered plan must
+  not include Option labels.
+-->
+```
+# [REMOVE IF UNUSED] Option 1: Single project (DEFAULT)
+src/
+├── models/
+├── services/
+├── cli/
+└── lib/
+
+tests/
+├── contract/
+├── integration/
+└── unit/
+
+# [REMOVE IF UNUSED] Option 2: Web application (when "frontend" + "backend" detected)
+backend/
+├── src/
+│   ├── models/
+│   ├── services/
+│   └── api/
+└── tests/
+
+frontend/
+├── src/
+│   ├── components/
+│   ├── pages/
+│   └── services/
+└── tests/
+
+# [REMOVE IF UNUSED] Option 3: Mobile + API (when "iOS/Android" detected)
+api/
+└── [same as backend above]
+
+ios/ or android/
+└── [platform-specific structure: feature modules, UI flows, platform tests]
+```
+
+**Structure Decision**: [Document the selected structure and reference the real
+directories captured above]
+
+## Phase 0: Outline & Research
+1. **Extract unknowns from Technical Context** above:
+   - For each NEEDS CLARIFICATION → research task
+   - For each dependency → best practices task
+   - For each integration → patterns task
+
+2. **Generate and dispatch research agents**:
+   ```
+   For each unknown in Technical Context:
+     Task: "Research {unknown} for {feature context}"
+   For each technology choice:
+     Task: "Find best practices for {tech} in {domain}"
+   ```
+
+3. **Consolidate findings** in `research.md` using format:
+   - Decision: [what was chosen]
+   - Rationale: [why chosen]
+   - Alternatives considered: [what else evaluated]
+
+**Output**: research.md with all NEEDS CLARIFICATION resolved
+
+## Phase 1: Design & Contracts
+*Prerequisites: research.md complete*
+
+1. **Extract entities from feature spec** → `data-model.md`:
+   - Entity name, fields, relationships
+   - Validation rules from requirements
+   - State transitions if applicable
+
+2. **Generate API contracts** from functional requirements:
+   - For each user action → endpoint
+   - Use standard REST/GraphQL patterns
+   - Output OpenAPI/GraphQL schema to `/contracts/`
+
+3. **Generate contract tests** from contracts:
+   - One test file per endpoint
+   - Assert request/response schemas
+   - Tests must fail (no implementation yet)
+
+4. **Extract test scenarios** from user stories:
+   - Each story → integration test scenario
+   - Quickstart test = story validation steps
+
+5. **Update agent file incrementally** (O(1) operation):
+   - Run `.specify/scripts/bash/update-agent-context.sh cursor`
+     **IMPORTANT**: Execute it exactly as specified above. Do not add or remove any arguments.
+   - If exists: Add only NEW tech from current plan
+   - Preserve manual additions between markers
+   - Update recent changes (keep last 3)
+   - Keep under 150 lines for token efficiency
+   - Output to repository root
+
+**Output**: data-model.md, /contracts/*, failing tests, quickstart.md, agent-specific file
+
+## Phase 2: Task Planning Approach
+*This section describes what the /tasks command will do - DO NOT execute during /plan*
+
+**Task Generation Strategy**:
+- Load `.specify/templates/tasks-template.md` as base
+- Generate tasks from Phase 1 design docs (contracts, data model, quickstart)
+- Each contract → contract test task [P]
+- Each entity → model creation task [P] 
+- Each user story → integration test task
+- Implementation tasks to make tests pass
+
+**Ordering Strategy**:
+- TDD order: Tests before implementation 
+- Dependency order: Models before services before UI
+- Mark [P] for parallel execution (independent files)
+
+**Estimated Output**: 25-30 numbered, ordered tasks in tasks.md
+
+**IMPORTANT**: This phase is executed by the /tasks command, NOT by /plan
+
+## Phase 3+: Future Implementation
+*These phases are beyond the scope of the /plan command*
+
+**Phase 3**: Task execution (/tasks command creates tasks.md)  
+**Phase 4**: Implementation (execute tasks.md following constitutional principles)  
+**Phase 5**: Validation (run tests, execute quickstart.md, performance validation)
+
+## Complexity Tracking
+*Fill ONLY if Constitution Check has violations that must be justified*
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| [e.g., 4th project] | [current need] | [why 3 projects insufficient] |
+| [e.g., Repository pattern] | [specific problem] | [why direct DB access insufficient] |
+
+
+## Progress Tracking
+*This checklist is updated during execution flow*
+
+**Phase Status**:
+- [ ] Phase 0: Research complete (/plan command)
+- [ ] Phase 1: Design complete (/plan command)
+- [ ] Phase 2: Task planning complete (/plan command - describe approach only)
+- [ ] Phase 3: Tasks generated (/tasks command)
+- [ ] Phase 4: Implementation complete
+- [ ] Phase 5: Validation passed
+
+**Gate Status**:
+- [ ] Initial Constitution Check: PASS
+- [ ] Post-Design Constitution Check: PASS
+- [ ] All NEEDS CLARIFICATION resolved
+- [ ] Complexity deviations documented
+
+---
+*Based on Constitution v1.0.0 - See `/memory/constitution.md`*
diff --git a/.specify/templates/spec-template.md b/.specify/templates/spec-template.md
new file mode 100644
index 0000000000..7915e7dd11
--- /dev/null
+++ b/.specify/templates/spec-template.md
@@ -0,0 +1,116 @@
+# Feature Specification: [FEATURE NAME]
+
+**Feature Branch**: `[###-feature-name]`  
+**Created**: [DATE]  
+**Status**: Draft  
+**Input**: User description: "$ARGUMENTS"
+
+## Execution Flow (main)
+```
+1. Parse user description from Input
+   → If empty: ERROR "No feature description provided"
+2. Extract key concepts from description
+   → Identify: actors, actions, data, constraints
+3. For each unclear aspect:
+   → Mark with [NEEDS CLARIFICATION: specific question]
+4. Fill User Scenarios & Testing section
+   → If no clear user flow: ERROR "Cannot determine user scenarios"
+5. Generate Functional Requirements
+   → Each requirement must be testable
+   → Mark ambiguous requirements
+6. Identify Key Entities (if data involved)
+7. Run Review Checklist
+   → If any [NEEDS CLARIFICATION]: WARN "Spec has uncertainties"
+   → If implementation details found: ERROR "Remove tech details"
+8. Return: SUCCESS (spec ready for planning)
+```
+
+---
+
+## ⚡ Quick Guidelines
+- ✅ Focus on WHAT users need and WHY
+- ❌ Avoid HOW to implement (no tech stack, APIs, code structure)
+- 👥 Written for business stakeholders, not developers
+
+### Section Requirements
+- **Mandatory sections**: Must be completed for every feature
+- **Optional sections**: Include only when relevant to the feature
+- When a section doesn't apply, remove it entirely (don't leave as "N/A")
+
+### For AI Generation
+When creating this spec from a user prompt:
+1. **Mark all ambiguities**: Use [NEEDS CLARIFICATION: specific question] for any assumption you'd need to make
+2. **Don't guess**: If the prompt doesn't specify something (e.g., "login system" without auth method), mark it
+3. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
+4. **Common underspecified areas**:
+   - User types and permissions
+   - Data retention/deletion policies  
+   - Performance targets and scale
+   - Error handling behaviors
+   - Integration requirements
+   - Security/compliance needs
+
+---
+
+## User Scenarios & Testing *(mandatory)*
+
+### Primary User Story
+[Describe the main user journey in plain language]
+
+### Acceptance Scenarios
+1. **Given** [initial state], **When** [action], **Then** [expected outcome]
+2. **Given** [initial state], **When** [action], **Then** [expected outcome]
+
+### Edge Cases
+- What happens when [boundary condition]?
+- How does system handle [error scenario]?
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+- **FR-001**: System MUST [specific capability, e.g., "allow users to create accounts"]
+- **FR-002**: System MUST [specific capability, e.g., "validate email addresses"]  
+- **FR-003**: Users MUST be able to [key interaction, e.g., "reset their password"]
+- **FR-004**: System MUST [data requirement, e.g., "persist user preferences"]
+- **FR-005**: System MUST [behavior, e.g., "log all security events"]
+
+*Example of marking unclear requirements:*
+- **FR-006**: System MUST authenticate users via [NEEDS CLARIFICATION: auth method not specified - email/password, SSO, OAuth?]
+- **FR-007**: System MUST retain user data for [NEEDS CLARIFICATION: retention period not specified]
+
+### Key Entities *(include if feature involves data)*
+- **[Entity 1]**: [What it represents, key attributes without implementation]
+- **[Entity 2]**: [What it represents, relationships to other entities]
+
+---
+
+## Review & Acceptance Checklist
+*GATE: Automated checks run during main() execution*
+
+### Content Quality
+- [ ] No implementation details (languages, frameworks, APIs)
+- [ ] Focused on user value and business needs
+- [ ] Written for non-technical stakeholders
+- [ ] All mandatory sections completed
+
+### Requirement Completeness
+- [ ] No [NEEDS CLARIFICATION] markers remain
+- [ ] Requirements are testable and unambiguous  
+- [ ] Success criteria are measurable
+- [ ] Scope is clearly bounded
+- [ ] Dependencies and assumptions identified
+
+---
+
+## Execution Status
+*Updated by main() during processing*
+
+- [ ] User description parsed
+- [ ] Key concepts extracted
+- [ ] Ambiguities marked
+- [ ] User scenarios defined
+- [ ] Requirements generated
+- [ ] Entities identified
+- [ ] Review checklist passed
+
+---
diff --git a/.specify/templates/tasks-template.md b/.specify/templates/tasks-template.md
new file mode 100644
index 0000000000..a461eb87ea
--- /dev/null
+++ b/.specify/templates/tasks-template.md
@@ -0,0 +1,129 @@
+# Tasks: [FEATURE NAME]
+
+**Input**: Design documents from `/specs/[###-feature-name]/`
+**Prerequisites**: plan.md (required), research.md, data-model.md, contracts/
+
+## Execution Flow (main)
+```
+1. Load plan.md from feature directory
+   → If not found: ERROR "No implementation plan found"
+   → Extract: tech stack, libraries, structure
+2. Load optional design documents:
+   → data-model.md: Extract entities → model tasks
+   → contracts/: Each file → contract test task
+   → research.md: Extract decisions → setup tasks
+3. Generate tasks by category:
+   → Setup: project init, dependencies, linting
+   → Tests: contract tests, integration tests
+   → Core: models, services, CLI commands
+   → Integration: DB, middleware, logging
+   → Polish: unit tests, performance, docs
+4. Apply task rules:
+   → Different files = mark [P] for parallel
+   → Same file = sequential (no [P])
+   → Tests before implementation (TDD)
+5. Number tasks sequentially (T001, T002...)
+6. Generate dependency graph
+7. Create parallel execution examples
+8. Validate task completeness:
+   → All contracts have tests?
+   → All entities have models?
+   → All endpoints implemented?
+9. Return: SUCCESS (tasks ready for execution)
+```
+
+## Format: `[ID] [P?] Description`
+- **[P]**: Can run in parallel (different files, no dependencies)
+- Include exact file paths in descriptions
+
+## Path Conventions
+- **Single project**: `src/`, `tests/` at repository root
+- **Web app**: `backend/src/`, `frontend/src/`
+- **Mobile**: `api/src/`, `ios/src/` or `android/src/`
+- Paths shown below assume single project - adjust based on plan.md structure
+
+## Phase 3.1: Setup
+- [ ] T001 Create project structure per implementation plan
+- [ ] T002 Initialize [language] project with [framework] dependencies
+- [ ] T003 [P] Configure linting and formatting tools
+
+## Phase 3.2: Tests First (TDD) ⚠️ MUST COMPLETE BEFORE 3.3
+**CRITICAL: These tests MUST be written and MUST FAIL before ANY implementation**
+- [ ] T004 [P] Contract test POST /api/users in tests/contract/test_users_post.py
+- [ ] T005 [P] Contract test GET /api/users/{id} in tests/contract/test_users_get.py
+- [ ] T006 [P] Integration test user registration in tests/integration/test_registration.py
+- [ ] T007 [P] Integration test auth flow in tests/integration/test_auth.py
+
+## Phase 3.3: Core Implementation (ONLY after tests are failing)
+- [ ] T008 [P] User model in src/models/user.py
+- [ ] T009 [P] UserService CRUD in src/services/user_service.py
+- [ ] T010 [P] CLI --create-user in src/cli/user_commands.py
+- [ ] T011 POST /api/users endpoint
+- [ ] T012 GET /api/users/{id} endpoint
+- [ ] T013 Input validation
+- [ ] T014 Error handling and logging
+
+## Phase 3.4: Integration
+- [ ] T015 Connect UserService to DB
+- [ ] T016 Auth middleware
+- [ ] T017 Request/response logging
+- [ ] T018 CORS and security headers
+
+## Phase 3.5: Polish
+- [ ] T019 [P] Unit tests for validation in tests/unit/test_validation.py
+- [ ] T020 Performance tests (<200ms)
+- [ ] T021 [P] Update docs/api.md
+- [ ] T022 [P] Update ERD documentation if database schema changed
+- [ ] T023 Remove duplication
+- [ ] T024 Run manual-testing.md
+
+## Dependencies
+- Tests (T004-T007) before implementation (T008-T014)
+- T008 blocks T009, T015
+- T016 blocks T018
+- Implementation before polish (T019-T023)
+
+## Parallel Example
+```
+# Launch T004-T007 together:
+Task: "Contract test POST /api/users in tests/contract/test_users_post.py"
+Task: "Contract test GET /api/users/{id} in tests/contract/test_users_get.py"
+Task: "Integration test registration in tests/integration/test_registration.py"
+Task: "Integration test auth in tests/integration/test_auth.py"
+```
+
+## Notes
+- [P] tasks = different files, no dependencies
+- Verify tests fail before implementing
+- Commit after each task
+- Avoid: vague tasks, same file conflicts
+
+## Task Generation Rules
+*Applied during main() execution*
+
+1. **From Contracts**:
+   - Each contract file → contract test task [P]
+   - Each endpoint → implementation task
+   
+2. **From Data Model**:
+   - Each entity → model creation task [P]
+   - Relationships → service layer tasks
+   
+3. **From User Stories**:
+   - Each story → integration test [P]
+   - Quickstart scenarios → validation tasks
+
+4. **Ordering**:
+   - Setup → Tests → Models → Services → Endpoints → Polish
+   - Dependencies block parallel execution
+
+## Validation Checklist
+*GATE: Checked by main() before returning*
+
+- [ ] All contracts have corresponding tests
+- [ ] All entities have model tasks
+- [ ] All tests come before implementation
+- [ ] Parallel tasks truly independent
+- [ ] Each task specifies exact file path
+- [ ] No task modifies same file as another [P] task
+- [ ] ERD documentation tasks included if database schema changes
\ No newline at end of file
diff --git a/backend/.dockerignore b/backend/.dockerignore
index c0de4abf73..05b6fd2334 100644
--- a/backend/.dockerignore
+++ b/backend/.dockerignore
@@ -6,3 +6,10 @@ app.egg-info
 .coverage
 htmlcov
 .venv
+
+# ERD Package (development/documentation only)
+erd/
+scripts/generate_erd.py
+tests/unit/erd_tests/
+tests/performance/test_erd_*.py
+tests/integration/test_erd_*.py
diff --git a/backend/erd/__init__.py b/backend/erd/__init__.py
new file mode 100644
index 0000000000..45a0f3f787
--- /dev/null
+++ b/backend/erd/__init__.py
@@ -0,0 +1,63 @@
+"""
+ERD Package - Entity Relationship Diagram generation from SQLModel definitions.
+
+This package provides functionality to automatically generate Mermaid ERD diagrams
+from SQLModel class definitions, including validation and output formatting.
+
+Main Components:
+- generator: Main ERD generation logic
+- models: Data structures for model metadata
+- validation: ERD validation and error checking
+- discovery: SQLModel introspection and parsing
+- output: ERD output formatting and file handling
+- entities: Entity definition structures
+- fields: Field definition structures
+- relationships: Relationship definition and management
+- mermaid_validator: Mermaid syntax validation
+
+Usage:
+    from erd import ERDGenerator
+    
+    generator = ERDGenerator()
+    mermaid_code = generator.generate_erd()
+"""
+
+from .generator import ERDGenerator
+from .models import (
+    FieldMetadata,
+    ModelMetadata, 
+    RelationshipMetadata,
+    ConstraintMetadata
+)
+from .validation import (
+    ERDValidator,
+    ValidationResult,
+    ValidationError,
+    ErrorSeverity,
+    ValidationMode
+)
+from .output import ERDOutput
+from .entities import EntityDefinition
+from .relationships import RelationshipDefinition, RelationshipManager
+from .discovery import ModelDiscovery
+from .mermaid_validator import MermaidValidator
+
+__version__ = "1.0.0"
+__all__ = [
+    "ERDGenerator",
+    "FieldMetadata",
+    "ModelMetadata", 
+    "RelationshipMetadata",
+    "ConstraintMetadata",
+    "ERDValidator",
+    "ValidationResult",
+    "ValidationError",
+    "ErrorSeverity",
+    "ValidationMode",
+    "ERDOutput",
+    "EntityDefinition",
+    "RelationshipDefinition",
+    "RelationshipManager",
+    "ModelDiscovery",
+    "MermaidValidator",
+]
diff --git a/backend/erd/discovery.py b/backend/erd/discovery.py
new file mode 100644
index 0000000000..0965fad766
--- /dev/null
+++ b/backend/erd/discovery.py
@@ -0,0 +1,262 @@
+"""
+Multi-file model discovery capability for ERD Generator.
+This module handles discovery of SQLModel definitions across multiple files.
+"""
+
+import ast
+from pathlib import Path
+from typing import Any
+
+
+class ModelDiscovery:
+    """Handles discovery of SQLModel classes across multiple files."""
+
+    def __init__(self, base_path: str = "app"):
+        self.base_path = Path(base_path)
+        self.discovered_models: dict[str, Any] = {}
+        self.model_files: set[Path] = set()
+
+    def discover_model_files(self, start_path: str = None) -> set[Path]:
+        """
+        Discover all Python files that may contain SQLModel definitions.
+
+        Args:
+            start_path: Starting directory for discovery (defaults to base_path)
+
+        Returns:
+            Set of Path objects for Python files containing models
+        """
+        if start_path:
+            search_path = Path(start_path)
+            # If start_path is a specific file, use it directly
+            if search_path.is_file():
+                if self._contains_sqlmodel_import(search_path):
+                    return {search_path}
+                else:
+                    return set()
+            # If start_path is a directory, search in it
+        else:
+            search_path = self.base_path
+
+        model_files = set()
+
+        # Find all Python files in the search path
+        for py_file in search_path.rglob("*.py"):
+            if self._contains_sqlmodel_import(py_file):
+                model_files.add(py_file)
+
+        self.model_files = model_files
+        return model_files
+
+    def _contains_sqlmodel_import(self, file_path: Path) -> bool:
+        """Check if a Python file contains SQLModel imports."""
+        try:
+            with open(file_path, encoding="utf-8") as f:
+                content = f.read()
+                return "SQLModel" in content or "sqlmodel" in content.lower()
+        except (OSError, UnicodeDecodeError):
+            return False
+
+    def extract_model_classes(self, file_path: Path) -> list[dict[str, Any]]:
+        """
+        Extract SQLModel class definitions from a Python file.
+
+        Args:
+            file_path: Path to the Python file
+
+        Returns:
+            List of dictionaries containing model class information
+        """
+        models = []
+
+        try:
+            with open(file_path, encoding="utf-8") as f:
+                content = f.read()
+
+            tree = ast.parse(content)
+
+            for node in ast.walk(tree):
+                if isinstance(node, ast.ClassDef):
+                    if self._is_sqlmodel_class(node):
+                        model_info = {
+                            "name": node.name,
+                            "file_path": str(file_path),
+                            "line_number": node.lineno,
+                            "bases": [
+                                base.id if hasattr(base, "id") else str(base)
+                                for base in node.bases
+                            ],
+                            "table": self._has_table_attribute(node),
+                            "fields": self._extract_fields(node),
+                            "relationships": self._extract_relationships_from_class(node),
+                        }
+                        models.append(model_info)
+
+        except (OSError, UnicodeDecodeError, SyntaxError):
+            # Log error but continue processing other files
+            pass
+
+        return models
+
+    def _is_sqlmodel_class(self, class_node: ast.ClassDef) -> bool:
+        """Check if a class is a SQLModel database table class."""
+        # Check if it inherits from SQLModel (directly or indirectly)
+        has_sqlmodel = False
+        has_table_true = False
+        
+        # Check direct inheritance from SQLModel
+        for base in class_node.bases:
+            if hasattr(base, "id") and base.id == "SQLModel":
+                has_sqlmodel = True
+        
+        # Also check if any of the base classes might be SQLModel classes
+        # (for cases like User(UserBase, table=True) where UserBase inherits from SQLModel)
+        for base in class_node.bases:
+            if hasattr(base, "id"):
+                base_name = base.id
+                # Check if this base class might be a SQLModel class
+                # This is a simple heuristic - in a real implementation, 
+                # we'd need to track the class hierarchy
+                if "Base" in base_name or "Model" in base_name:
+                    has_sqlmodel = True
+        
+        # Check for table=True in the class definition keywords
+        # This handles cases like: class User(UserBase, table=True):
+        for keyword in class_node.keywords:
+            if keyword.arg == "table" and isinstance(keyword.value, ast.Constant):
+                if keyword.value.value is True:
+                    has_table_true = True
+        
+        # Only return True if it's both a SQLModel AND has table=True
+        return has_sqlmodel and has_table_true
+
+    def _extract_relationships_from_class(self, class_node: ast.ClassDef) -> list[dict]:
+        """Extract relationship definitions from a SQLModel class."""
+        relationships = []
+        
+        for item in class_node.body:
+            if isinstance(item, ast.AnnAssign) and isinstance(item.target, ast.Name):
+                # Check if it's a Relationship() call
+                if (isinstance(item.value, ast.Call) and 
+                    hasattr(item.value.func, 'id') and 
+                    item.value.func.id == 'Relationship'):
+                    
+                    field_name = item.target.id
+                    field_type = ast.unparse(item.annotation) if item.annotation else "Any"
+                    
+                    # Extract relationship metadata
+                    back_populates = None
+                    cascade_delete = False
+                    
+                    for keyword in item.value.keywords:
+                        if keyword.arg == "back_populates" and isinstance(keyword.value, ast.Constant):
+                            back_populates = keyword.value.value
+                        elif keyword.arg == "cascade_delete" and isinstance(keyword.value, ast.Constant):
+                            cascade_delete = keyword.value.value
+                    
+                    # Infer target model from field type
+                    target_model = self._infer_target_model_from_type(field_type, back_populates)
+                    
+                    # Determine relationship type
+                    relationship_type = self._determine_relationship_type_from_field_type(field_type)
+                    
+                    relationships.append({
+                        "field_name": field_name,
+                        "field_type": field_type,
+                        "target_model": target_model,
+                        "relationship_type": relationship_type,
+                        "back_populates": back_populates,
+                        "cascade_delete": cascade_delete,
+                    })
+        
+        return relationships
+
+    def _infer_target_model_from_type(self, field_type: str, back_populates: str | None) -> str:
+        """Infer target model name from field type annotation."""
+        # Handle list types like list["Item"] or List[Item]
+        if "list[" in field_type.lower() or "List[" in field_type:
+            # Extract type from list annotation
+            if '"' in field_type:
+                # Extract double-quoted type name
+                start = field_type.find('"') + 1
+                end = field_type.find('"', start)
+                if end > start:
+                    result = field_type[start:end]
+                    return result.strip("'\"")
+            elif "'" in field_type:
+                # Extract single-quoted type name
+                start = field_type.find("'") + 1
+                end = field_type.find("'", start)
+                if end > start:
+                    result = field_type[start:end]
+                    return result.strip("'\"")
+            elif '[' in field_type and ']' in field_type:
+                # Extract type from brackets
+                start = field_type.find('[') + 1
+                end = field_type.find(']', start)
+                if end > start:
+                    return field_type[start:end].strip()
+        
+        # Handle union types like User | None
+        if "|" in field_type:
+            # Extract the non-None type
+            types = [t.strip() for t in field_type.split("|")]
+            for t in types:
+                if t != "None":
+                    return t
+        
+        # Fallback: use back_populates if available
+        if back_populates:
+            return back_populates.title()
+        
+        return "Unknown"
+
+    def _determine_relationship_type_from_field_type(self, field_type: str) -> str:
+        """Determine relationship type from field type annotation."""
+        field_type_lower = field_type.lower()
+        
+        if "list[" in field_type_lower or "List[" in field_type_lower:
+            return "one-to-many"
+        elif "| None" in field_type_lower:
+            return "many-to-one"
+        else:
+            # Default to many-to-one for relationship fields (they're usually foreign keys)
+            return "many-to-one"
+
+    def _has_table_attribute(self, class_node: ast.ClassDef) -> bool:
+        """Check if a class has table=True attribute."""
+        for base in class_node.bases:
+            if hasattr(base, "keywords"):
+                for keyword in base.keywords:
+                    if keyword.arg == "table" and isinstance(
+                        keyword.value, ast.Constant
+                    ):
+                        return keyword.value.value is True
+        return False
+
+    def _extract_fields(self, class_node: ast.ClassDef) -> list[str]:
+        """Extract field names from a class definition."""
+        fields = []
+        for node in class_node.body:
+            if isinstance(node, ast.AnnAssign) and isinstance(node.target, ast.Name):
+                field_name = node.target.id
+                # Skip private fields (starting with _)
+                if not field_name.startswith('_'):
+                    fields.append(field_name)
+        return fields
+
+    def discover_all_models(self) -> dict[str, list[dict[str, Any]]]:
+        """
+        Discover all SQLModel classes across all discovered files.
+
+        Returns:
+            Dictionary mapping file paths to lists of model information
+        """
+        all_models = {}
+
+        for file_path in self.discover_model_files():
+            models = self.extract_model_classes(file_path)
+            if models:
+                all_models[str(file_path)] = models
+
+        return all_models
diff --git a/backend/erd/entities.py b/backend/erd/entities.py
new file mode 100644
index 0000000000..7adb9b01e5
--- /dev/null
+++ b/backend/erd/entities.py
@@ -0,0 +1,197 @@
+"""
+Entity Definition entity for individual entities (tables) in ERD.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class FieldDefinition:
+    """Definition of a field in an entity."""
+
+    name: str
+    type: str
+    constraints: list[str] = field(default_factory=list)
+    is_primary_key: bool = False
+    is_foreign_key: bool = False
+    is_nullable: bool = True
+    default_value: str | None = None
+    description: str | None = None
+
+    def __post_init__(self):
+        if self.is_primary_key:
+            self.constraints.append("PK")
+        if self.is_foreign_key:
+            self.constraints.append("FK")
+        if not self.is_nullable:
+            self.constraints.append("NOT NULL")
+
+    def to_mermaid_field(self) -> str:
+        """Convert field to Mermaid ERD field syntax."""
+        field_parts = [self.type, self.name]
+
+        if self.constraints:
+            constraint_str = " ".join(self.constraints)
+            field_parts.append(constraint_str)
+
+        return " ".join(field_parts)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert field definition to dictionary."""
+        return {
+            "name": self.name,
+            "type": self.type,
+            "constraints": self.constraints,
+            "is_primary_key": self.is_primary_key,
+            "is_foreign_key": self.is_foreign_key,
+            "is_nullable": self.is_nullable,
+            "default_value": self.default_value,
+            "description": self.description,
+        }
+
+
+@dataclass
+class EntityDefinition:
+    """Individual entity (table) definition in ERD."""
+
+    name: str
+    fields: list[FieldDefinition]
+    description: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        # Ensure entity name is uppercase for ERD
+        self.name = self.name.upper()
+
+    @property
+    def primary_key_fields(self) -> list[FieldDefinition]:
+        """Get all primary key fields."""
+        return [field for field in self.fields if field.is_primary_key]
+
+    @property
+    def foreign_key_fields(self) -> list[FieldDefinition]:
+        """Get all foreign key fields."""
+        return [field for field in self.fields if field.is_foreign_key]
+
+    @property
+    def has_relationships(self) -> bool:
+        """Check if entity has foreign key relationships."""
+        return len(self.foreign_key_fields) > 0
+
+    def get_field_by_name(self, field_name: str) -> FieldDefinition | None:
+        """Get a field by its name."""
+        for field_def in self.fields:
+            if field_def.name == field_name:
+                return field_def
+        return None
+
+    def add_field(self, field: FieldDefinition) -> None:
+        """Add a field to the entity."""
+        self.fields.append(field)
+
+    def to_mermaid_entity(self) -> str:
+        """Convert entity to Mermaid ERD entity syntax."""
+        lines = [f"{self.name} {{"]
+
+        for field_def in self.fields:
+            lines.append(f"    {field_def.to_mermaid_field()}")
+
+        lines.append("}")
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert entity definition to dictionary."""
+        return {
+            "name": self.name,
+            "fields": [field.to_dict() for field in self.fields],
+            "description": self.description,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_model_metadata(cls, model_metadata) -> "EntityDefinition":
+        """Create EntityDefinition from ModelMetadata."""
+        fields = []
+
+        for field_meta in model_metadata.fields:
+            # Convert type hint to Mermaid type
+            mermaid_type = cls._convert_type_to_mermaid(field_meta.type_hint)
+
+            field_def = FieldDefinition(
+                name=field_meta.name,
+                type=mermaid_type,
+                constraints=[],  # Will be set in __post_init__
+                is_primary_key=field_meta.is_primary_key,
+                is_foreign_key=field_meta.is_foreign_key,
+                is_nullable=field_meta.is_nullable,
+                default_value=(
+                    str(field_meta.default_value)
+                    if field_meta.default_value is not None
+                    else None
+                ),
+            )
+            fields.append(field_def)
+
+        return cls(
+            name=model_metadata.table_name,
+            fields=fields,
+            description=f"Table for {model_metadata.class_name} model",
+            metadata={
+                "class_name": model_metadata.class_name,
+                "file_path": str(model_metadata.file_path),
+                "line_number": model_metadata.line_number,
+            },
+        )
+
+    @staticmethod
+    def _convert_type_to_mermaid(type_hint: str) -> str:
+        """Convert Python type hint to Mermaid ERD type."""
+        type_hint = type_hint.lower()
+
+        # Common type mappings
+        type_mappings = {
+            "str": "string",
+            "string": "string",
+            "int": "int",
+            "integer": "int",
+            "float": "float",
+            "bool": "boolean",
+            "boolean": "boolean",
+            "datetime": "datetime",
+            "date": "date",
+            "time": "time",
+            "uuid": "uuid",
+            "json": "json",
+            "text": "text",
+            "bytes": "bytes",
+            "bytea": "bytes",
+        }
+
+        # Handle Optional types
+        if "optional" in type_hint or "union" in type_hint:
+            # Extract the inner type
+            for key in type_mappings:
+                if key in type_hint:
+                    return type_mappings[key]
+
+        # Handle List types
+        if "list" in type_hint or "array" in type_hint:
+            return "array"
+
+        # Direct mapping
+        for key, value in type_mappings.items():
+            if key in type_hint:
+                return value
+
+        # Default fallback
+        if "uuid" in type_hint:
+            return "uuid"
+        elif "datetime" in type_hint:
+            return "datetime"
+        elif "int" in type_hint:
+            return "int"
+        elif "str" in type_hint:
+            return "string"
+        else:
+            return "string"  # Safe fallback
diff --git a/backend/erd/fields.py b/backend/erd/fields.py
new file mode 100644
index 0000000000..8ae51e7f40
--- /dev/null
+++ b/backend/erd/fields.py
@@ -0,0 +1,241 @@
+"""
+Field Definition entity for detailed field information in ERD.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class FieldType(Enum):
+    """Enumeration of supported field types."""
+
+    STRING = "string"
+    INTEGER = "int"
+    FLOAT = "float"
+    BOOLEAN = "boolean"
+    DATETIME = "datetime"
+    DATE = "date"
+    TIME = "time"
+    UUID = "uuid"
+    JSON = "json"
+    TEXT = "text"
+    BYTES = "bytes"
+    ARRAY = "array"
+    ENUM = "enum"
+
+
+class ConstraintType(Enum):
+    """Enumeration of constraint types."""
+
+    PRIMARY_KEY = "PK"
+    FOREIGN_KEY = "FK"
+    NOT_NULL = "NOT NULL"
+    UNIQUE = "UNIQUE"
+    CHECK = "CHECK"
+    DEFAULT = "DEFAULT"
+
+
+@dataclass
+class Constraint:
+    """Database constraint definition."""
+
+    type: ConstraintType
+    value: str | None = None
+    referenced_table: str | None = None
+    referenced_column: str | None = None
+
+    def to_string(self) -> str:
+        """Convert constraint to string representation."""
+        if self.type == ConstraintType.DEFAULT and self.value:
+            return f"DEFAULT {self.value}"
+        elif self.type == ConstraintType.CHECK and self.value:
+            return f"CHECK {self.value}"
+        elif self.type == ConstraintType.FOREIGN_KEY and self.referenced_table:
+            ref = f"{self.referenced_table}"
+            if self.referenced_column:
+                ref += f".{self.referenced_column}"
+            return f"FK -> {ref}"
+        else:
+            return self.type.value
+
+
+@dataclass
+class FieldDefinition:
+    """Detailed field definition for ERD generation."""
+
+    name: str
+    type: FieldType
+    constraints: list[Constraint] = field(default_factory=list)
+    is_primary_key: bool = False
+    is_foreign_key: bool = False
+    is_nullable: bool = True
+    is_unique: bool = False
+    default_value: str | int | float | bool | None = None
+    max_length: int | None = None
+    precision: int | None = None
+    scale: int | None = None
+    description: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Initialize constraints based on field properties."""
+        if self.is_primary_key:
+            self.constraints.append(Constraint(ConstraintType.PRIMARY_KEY))
+        if self.is_foreign_key:
+            self.constraints.append(Constraint(ConstraintType.FOREIGN_KEY))
+        if not self.is_nullable:
+            self.constraints.append(Constraint(ConstraintType.NOT_NULL))
+        if self.is_unique:
+            self.constraints.append(Constraint(ConstraintType.UNIQUE))
+        if self.default_value is not None:
+            self.constraints.append(
+                Constraint(ConstraintType.DEFAULT, str(self.default_value))
+            )
+
+    @property
+    def mermaid_type(self) -> str:
+        """Get the Mermaid ERD type representation."""
+        type_str = self.type.value
+
+        # Add size information for string types
+        if self.type == FieldType.STRING and self.max_length:
+            type_str = f"{type_str}({self.max_length})"
+
+        # Add precision/scale for numeric types
+        if self.type in [FieldType.FLOAT] and self.precision:
+            if self.scale:
+                type_str = f"{type_str}({self.precision},{self.scale})"
+            else:
+                type_str = f"{type_str}({self.precision})"
+
+        return type_str
+
+    @property
+    def constraint_strings(self) -> list[str]:
+        """Get list of constraint strings."""
+        return [constraint.to_string() for constraint in self.constraints]
+
+    def to_mermaid_field(self) -> str:
+        """Convert field to Mermaid ERD field syntax."""
+        field_parts = [self.mermaid_type, self.name]
+
+        if self.constraints:
+            constraint_str = " ".join(self.constraint_strings)
+            field_parts.append(constraint_str)
+
+        return " ".join(field_parts)
+
+    def add_constraint(self, constraint: Constraint) -> None:
+        """Add a constraint to the field."""
+        self.constraints.append(constraint)
+
+    def remove_constraint(self, constraint_type: ConstraintType) -> None:
+        """Remove constraints of a specific type."""
+        self.constraints = [c for c in self.constraints if c.type != constraint_type]
+
+    def has_constraint(self, constraint_type: ConstraintType) -> bool:
+        """Check if field has a specific constraint type."""
+        return any(c.type == constraint_type for c in self.constraints)
+
+    def set_foreign_key_reference(
+        self, referenced_table: str, referenced_column: str = None
+    ) -> None:
+        """Set foreign key reference information."""
+        # Remove existing FK constraint
+        self.remove_constraint(ConstraintType.FOREIGN_KEY)
+
+        # Add new FK constraint with reference
+        fk_constraint = Constraint(
+            ConstraintType.FOREIGN_KEY,
+            referenced_table=referenced_table,
+            referenced_column=referenced_column,
+        )
+        self.constraints.append(fk_constraint)
+        self.is_foreign_key = True
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert field definition to dictionary."""
+        return {
+            "name": self.name,
+            "type": self.type.value,
+            "constraints": [c.to_string() for c in self.constraints],
+            "is_primary_key": self.is_primary_key,
+            "is_foreign_key": self.is_foreign_key,
+            "is_nullable": self.is_nullable,
+            "is_unique": self.is_unique,
+            "default_value": self.default_value,
+            "max_length": self.max_length,
+            "precision": self.precision,
+            "scale": self.scale,
+            "description": self.description,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_model_field(cls, field_metadata) -> "FieldDefinition":
+        """Create FieldDefinition from ModelMetadata field."""
+        # Convert type hint to FieldType
+        field_type = cls._convert_type_to_field_type(field_metadata.type_hint)
+
+        # Create field definition
+        field_def = cls(
+            name=field_metadata.name,
+            type=field_type,
+            is_primary_key=field_metadata.is_primary_key,
+            is_foreign_key=field_metadata.is_foreign_key,
+            is_nullable=field_metadata.is_nullable,
+            default_value=field_metadata.default_value,
+        )
+
+        # Set foreign key reference if available
+        if field_metadata.foreign_key_reference:
+            parts = field_metadata.foreign_key_reference.split(".")
+            if len(parts) >= 2:
+                field_def.set_foreign_key_reference(parts[0], parts[1])
+            else:
+                field_def.set_foreign_key_reference(parts[0])
+
+        return field_def
+
+    @staticmethod
+    def _convert_type_to_field_type(type_hint: str) -> FieldType:
+        """Convert Python type hint to FieldType enum."""
+        type_hint = type_hint.lower()
+
+        # Handle Optional and Union types
+        if "optional" in type_hint or "union" in type_hint:
+            # Extract the inner type
+            for field_type in FieldType:
+                if field_type.value in type_hint:
+                    return field_type
+
+        # Handle List types
+        if "list" in type_hint or "array" in type_hint:
+            return FieldType.ARRAY
+
+        # Direct mappings
+        type_mappings = {
+            "str": FieldType.STRING,
+            "string": FieldType.STRING,
+            "int": FieldType.INTEGER,
+            "integer": FieldType.INTEGER,
+            "float": FieldType.FLOAT,
+            "bool": FieldType.BOOLEAN,
+            "boolean": FieldType.BOOLEAN,
+            "datetime": FieldType.DATETIME,
+            "date": FieldType.DATE,
+            "time": FieldType.TIME,
+            "uuid": FieldType.UUID,
+            "json": FieldType.JSON,
+            "text": FieldType.TEXT,
+            "bytes": FieldType.BYTES,
+            "bytea": FieldType.BYTES,
+        }
+
+        for key, value in type_mappings.items():
+            if key in type_hint:
+                return value
+
+        # Default fallback
+        return FieldType.STRING
diff --git a/backend/erd/generator.py b/backend/erd/generator.py
new file mode 100644
index 0000000000..289bdc2d77
--- /dev/null
+++ b/backend/erd/generator.py
@@ -0,0 +1,462 @@
+"""
+ERD Generator Module - Main entity responsible for generating Mermaid ERD diagrams from SQLModel definitions.
+"""
+
+from datetime import datetime
+from pathlib import Path
+
+from .entities import EntityDefinition
+from .discovery import ModelDiscovery
+from .models import FieldMetadata, ModelMetadata, RelationshipMetadata
+from .output import ERDOutput
+from .relationships import RelationshipDefinition, RelationshipManager
+from .validation import ERDValidator
+from .mermaid_validator import MermaidValidator
+
+
+class ERDGenerator:
+    """Main entity responsible for generating Mermaid ERD diagrams from SQLModel definitions."""
+
+    def __init__(
+        self,
+        models_path: str = "app/models.py",
+        output_path: str = "../docs/database/erd.mmd",
+    ):
+        self.models_path = models_path
+        self.output_path = output_path
+        self.mermaid_syntax = {}
+        self.validation_rules = {}
+        self.model_discovery = ModelDiscovery()
+        self.generated_models: dict[str, ModelMetadata] = {}
+        self.relationship_manager = RelationshipManager()
+        self.validator = ERDValidator()
+        self.mermaid_validator = MermaidValidator()
+
+    def generate_erd(self) -> str:
+        """Generate Mermaid ERD diagram from SQLModel definitions."""
+        try:
+            # Step 1: Discover and parse models
+            self._discover_models()
+
+            # Step 2: Extract metadata from models
+            self._extract_model_metadata()
+
+            # Step 3: Generate entities
+            entities = self._generate_entities()
+
+            # Step 4: Generate relationships
+            relationships = self._generate_relationships()
+
+            # Step 5: Generate Mermaid code
+            mermaid_code = self._generate_mermaid_code(entities, relationships)
+
+            # Step 6: Create ERD output
+            erd_output = ERDOutput(
+                mermaid_code=mermaid_code,
+                entities=[entity.to_dict() for entity in entities],
+                relationships=[rel.to_dict() for rel in relationships],
+                metadata={
+                    "generated_at": datetime.now().isoformat(),
+                    "models_processed": len(self.generated_models),
+                    "entities_count": len(entities),
+                    "relationships_count": len(relationships),
+                },
+            )
+
+            # Step 7: Validate the generated ERD
+            validation_result = self.validator.validate_all(mermaid_code)
+            
+            # Step 8: Validate Mermaid syntax
+            mermaid_validation = self.mermaid_validator.validate_complete(mermaid_code)
+            validation_result.errors.extend(mermaid_validation.errors)
+            validation_result.warnings.extend(mermaid_validation.warnings)
+            if not mermaid_validation.is_valid:
+                validation_result.is_valid = False
+
+            # Update ERD output with validation results
+            if validation_result.is_valid:
+                erd_output.mark_as_valid()
+            else:
+                erd_output.mark_as_invalid()
+                erd_output.metadata["validation_errors"] = [
+                    {
+                        "message": error.message,
+                        "severity": error.severity.value,
+                        "line_number": error.line_number,
+                        "error_code": error.error_code,
+                    }
+                    for error in validation_result.errors
+                ]
+                erd_output.metadata["validation_warnings"] = [
+                    {
+                        "message": warning.message,
+                        "severity": warning.severity.value,
+                        "line_number": warning.line_number,
+                        "error_code": warning.error_code,
+                    }
+                    for warning in validation_result.warnings
+                ]
+
+            # Step 9: Write output to file
+            self._write_output(erd_output)
+
+            return mermaid_code
+
+        except Exception as e:
+            error_msg = f"ERD generation failed: {str(e)}"
+            # Create error output
+            error_output = ERDOutput(
+                mermaid_code="erDiagram\n    ERROR {\n        string message\n    }",
+                entities=[],
+                relationships=[],
+                validation_status="error",
+            )
+            error_output.mark_as_error(error_msg)
+            self._write_output(error_output)
+            raise Exception(error_msg) from e
+
+    def validate_models(self) -> bool:
+        """Validate SQLModel definitions for ERD generation."""
+        try:
+            # Discover models first
+            self._discover_models()
+
+            # Extract metadata
+            self._extract_model_metadata()
+
+            # Basic validation checks
+            if not self.generated_models:
+                raise ValueError("No SQLModel classes found")
+
+            validation_errors = []
+
+            for model_name, model_metadata in self.generated_models.items():
+                if not model_metadata.primary_key:
+                    validation_errors.append(f"Model {model_name} has no primary key")
+
+                if not model_metadata.fields:
+                    validation_errors.append(f"Model {model_name} has no fields")
+
+                # Validate field types and constraints
+                for field in model_metadata.fields:
+                    if not field.type_hint or field.type_hint == "Any":
+                        validation_errors.append(f"Model {model_name}.{field.name} has no type hint")
+
+            if validation_errors:
+                print("Validation errors found:")
+                for error in validation_errors:
+                    print(f"  - {error}")
+                return False
+
+            return True
+
+        except Exception as e:
+            print(f"Validation failed: {e}")
+            return False
+
+    def _discover_models(self) -> None:
+        """Discover SQLModel files and classes."""
+        # Use the model discovery to find all model files
+        model_files = self.model_discovery.discover_model_files(self.models_path)
+
+        if not model_files:
+            # Fallback to the specified models path
+            models_path = Path(self.models_path)
+            if models_path.exists():
+                model_files = {models_path}
+            else:
+                raise FileNotFoundError(f"Models file not found: {self.models_path}")
+
+        # Extract models from all discovered files
+        for file_path in model_files:
+            models = self.model_discovery.extract_model_classes(file_path)
+            for model_info in models:
+                self.generated_models[model_info["name"]] = model_info
+
+    def _extract_model_metadata(self) -> None:
+        """Extract detailed metadata from discovered models."""
+        for model_name, model_info in self.generated_models.items():
+            # Convert basic model info to ModelMetadata with enhanced introspection
+            fields = []
+            relationships = []
+            constraints = []
+
+            # Enhanced field extraction with type hints and constraints
+            for field_name in model_info.get("fields", []):
+                field_meta = self._create_field_metadata(model_info, field_name)
+                
+                # Skip relationship fields - they're not database columns
+                if not self._is_relationship_field(field_meta, model_info):
+                    fields.append(field_meta)
+
+            # Extract relationships from the model
+            relationships = self._extract_relationships(model_info)
+
+            # Extract constraints (empty for now)
+            constraints = []
+
+            model_metadata = ModelMetadata(
+                class_name=model_info["name"],
+                table_name=model_info["name"].lower(),
+                file_path=Path(model_info["file_path"]),
+                line_number=model_info["line_number"],
+                fields=fields,
+                relationships=relationships,
+                constraints=constraints,
+            )
+
+            self.generated_models[model_name] = model_metadata
+
+    def _is_relationship_field(self, field_meta: FieldMetadata, model_info: dict) -> bool:
+        """Check if a field is a relationship field (not a database column)."""
+        # Check if this field is defined as a Relationship() in the model
+        for rel_info in model_info.get("relationships", []):
+            if rel_info["field_name"] == field_meta.name:
+                return True
+        
+        # Check field type for relationship indicators
+        field_type = field_meta.type_hint.lower()
+        
+        # List types are usually relationships (e.g., list["Item"])
+        if "list[" in field_type or "List[" in field_type:
+            return True
+        
+        # Union types with None might be relationships (e.g., User | None)
+        if "| None" in field_type and not field_meta.is_foreign_key:
+            return True
+        
+        return False
+
+    def _is_bidirectional_relationship(self, rel_meta: RelationshipMetadata, target_model: ModelMetadata) -> bool:
+        """Check if a relationship is bidirectional (has back_populates)."""
+        # Check if this relationship has back_populates
+        if not rel_meta.back_populates:
+            return False
+        
+        # Check if the target model has a corresponding relationship with back_populates pointing back
+        for target_rel in target_model.relationships:
+            # The target relationship should have back_populates pointing to our field_name
+            # and should point to our source model
+            if (target_rel.back_populates == rel_meta.field_name):
+                return True
+        
+        return False
+
+    def _generate_entities(self) -> list[EntityDefinition]:
+        """Generate entity definitions from model metadata."""
+        entities = []
+
+        for _model_name, model_metadata in self.generated_models.items():
+            entity = EntityDefinition.from_model_metadata(model_metadata)
+            entities.append(entity)
+
+        return entities
+
+    def _generate_relationships(self) -> list[RelationshipDefinition]:
+        """Generate relationship definitions, avoiding redundant bidirectional relationships."""
+        relationships = []
+        processed_pairs = set()  # Track which entity pairs we've already handled
+
+        # Generate relationships from relationship metadata
+        for model_name, model_metadata in self.generated_models.items():
+            for rel_meta in model_metadata.relationships:
+                # Find target model
+                target_model_name = rel_meta.target_model
+                if target_model_name in self.generated_models:
+                    target_model = self.generated_models[target_model_name]
+                    
+                    # Create relationship key for bidirectional detection
+                    pair_key = tuple(sorted([model_name, target_model_name]))
+                    
+                    if pair_key not in processed_pairs:
+                        # Check if this is bidirectional
+                        if self._is_bidirectional_relationship(rel_meta, target_model):
+                            # Always prefer the one-to-many direction
+                            if rel_meta.relationship_type == "one-to-many":
+                                relationship = RelationshipDefinition.from_model_relationship(
+                                    rel_meta, model_metadata, target_model
+                                )
+                                relationships.append(relationship)
+                                processed_pairs.add(pair_key)
+                        else:
+                            # Non-bidirectional, render normally
+                            relationship = RelationshipDefinition.from_model_relationship(
+                                rel_meta, model_metadata, target_model
+                            )
+                            relationships.append(relationship)
+
+        # Also generate relationships from foreign key fields (fallback)
+        for _model_name, model_metadata in self.generated_models.items():
+            for field in model_metadata.foreign_key_fields:
+                # Find target model (simple heuristic)
+                target_model_name = self._find_target_model(field.name)
+                if target_model_name and target_model_name in self.generated_models:
+                    target_model = self.generated_models[target_model_name]
+                    
+                    # Create relationship key for bidirectional detection
+                    pair_key = tuple(sorted([_model_name, target_model_name]))
+                    
+                    if pair_key not in processed_pairs:
+                        relationship = RelationshipDefinition.from_foreign_key(
+                            model_metadata, target_model, field
+                        )
+                        relationships.append(relationship)
+                        processed_pairs.add(pair_key)
+
+        return relationships
+
+    def _find_target_model(self, field_name: str) -> str | None:
+        """Find target model for a foreign key field."""
+        # Simple heuristic: remove _id suffix and capitalize
+        if field_name.endswith("_id"):
+            model_name = field_name[:-3].title()
+            return model_name
+        return None
+
+    def _generate_mermaid_code(
+        self,
+        entities: list[EntityDefinition],
+        relationships: list[RelationshipDefinition],
+    ) -> str:
+        """Generate Mermaid ERD code from entities and relationships."""
+        lines = ["erDiagram"]
+
+        # Add entities
+        for entity in entities:
+            lines.append("")
+            lines.append(entity.to_mermaid_entity())
+
+        # Add relationships
+        if relationships:
+            lines.append("")
+            for relationship in relationships:
+                lines.append(relationship.to_mermaid_relationship())
+
+        return "\n".join(lines)
+
+    def _write_output(self, erd_output: ERDOutput) -> None:
+        """Write ERD output to file."""
+        output_path = Path(self.output_path)
+        output_path.parent.mkdir(parents=True, exist_ok=True)
+
+        mermaid_content = erd_output.to_mermaid_format()
+        output_path.write_text(mermaid_content, encoding="utf-8")
+
+    def _create_field_metadata(self, model_info: dict, field_name: str) -> FieldMetadata:
+        """Create enhanced field metadata with type hints and constraints."""
+        # Parse the actual model file to get detailed field information
+        file_path = Path(model_info["file_path"])
+        field_meta = self._parse_field_from_source(file_path, model_info["name"], field_name)
+
+        # If parsing failed, use basic heuristics
+        if not field_meta:
+            field_meta = FieldMetadata(
+                name=field_name,
+                type_hint=self._infer_field_type(field_name),
+                is_primary_key=field_name == "id",
+                is_foreign_key=field_name.endswith("_id"),
+                is_nullable=True,
+            )
+
+        return field_meta
+
+    def _parse_field_from_source(self, file_path: Path, class_name: str, field_name: str) -> FieldMetadata | None:
+        """Parse field information from the source file using AST."""
+        try:
+            import ast
+
+            with open(file_path, encoding='utf-8') as f:
+                content = f.read()
+
+            tree = ast.parse(content)
+
+            for node in ast.walk(tree):
+                if isinstance(node, ast.ClassDef) and node.name == class_name:
+                    for item in node.body:
+                        if isinstance(item, ast.AnnAssign) and isinstance(item.target, ast.Name):
+                            if item.target.id == field_name:
+                                # Extract type hint
+                                type_hint = ast.unparse(item.annotation) if item.annotation else "Any"
+
+                                # Check for Field() call
+                                is_primary_key = False
+                                is_foreign_key = False
+                                is_nullable = True
+                                foreign_key_ref = None
+
+                                if isinstance(item.value, ast.Call):
+                                    # Parse Field() arguments
+                                    for keyword in item.value.keywords:
+                                        if keyword.arg == "primary_key" and isinstance(keyword.value, ast.Constant):
+                                            is_primary_key = keyword.value.value
+                                        elif keyword.arg == "foreign_key" and isinstance(keyword.value, ast.Constant):
+                                            foreign_key_ref = keyword.value.value
+                                            is_foreign_key = True
+                                        elif keyword.arg == "nullable" and isinstance(keyword.value, ast.Constant):
+                                            is_nullable = keyword.value.value
+
+                                return FieldMetadata(
+                                    name=field_name,
+                                    type_hint=type_hint,
+                                    is_primary_key=is_primary_key,
+                                    is_foreign_key=is_foreign_key,
+                                    is_nullable=is_nullable,
+                                    foreign_key_reference=foreign_key_ref,
+                                )
+        except Exception:
+            pass
+
+        return None
+
+    def _infer_field_type(self, field_name: str) -> str:
+        """Infer field type from field name."""
+        if field_name == "id":
+            return "UUID"
+        elif field_name.endswith("_id"):
+            return "UUID"
+        elif field_name in ["email", "name", "title", "description"]:
+            return "str"
+        elif field_name in ["created_at", "updated_at", "timestamp"]:
+            return "datetime"
+        elif field_name in ["is_active", "is_superuser", "enabled"]:
+            return "bool"
+        else:
+            return "str"
+
+    def _extract_relationships(self, model_info: dict) -> list[RelationshipMetadata]:
+        """Extract relationships from model info."""
+        relationships = []
+        
+        # Extract relationships from the discovered relationship data
+        for rel_info in model_info.get("relationships", []):
+            rel_meta = RelationshipMetadata(
+                field_name=rel_info["field_name"],
+                target_model=rel_info["target_model"],
+                relationship_type=rel_info["relationship_type"],
+                back_populates=rel_info.get("back_populates"),
+                cascade=rel_info.get("cascade_delete", False),
+            )
+            relationships.append(rel_meta)
+        
+        # Also extract foreign key relationships from field names (fallback)
+        for field_name in model_info.get("fields", []):
+            if field_name.endswith("_id") and field_name != "id":
+                # Check if we already have a relationship for this field
+                existing_rel = any(
+                    rel.field_name == field_name or rel.foreign_key_field == field_name
+                    for rel in relationships
+                )
+                
+                if not existing_rel:
+                    # This looks like a foreign key relationship
+                    target_model = field_name[:-3].title()  # Remove _id and capitalize
+                    rel_meta = RelationshipMetadata(
+                        field_name=field_name,
+                        target_model=target_model,
+                        relationship_type="many-to-one",
+                        foreign_key_field=field_name,
+                    )
+                    relationships.append(rel_meta)
+        
+        return relationships
+
diff --git a/backend/erd/mermaid_validator.py b/backend/erd/mermaid_validator.py
new file mode 100644
index 0000000000..bb921dbd72
--- /dev/null
+++ b/backend/erd/mermaid_validator.py
@@ -0,0 +1,201 @@
+"""
+Mermaid syntax validation for ERD diagrams.
+"""
+
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from .validation import ValidationResult, ValidationError, ErrorSeverity
+
+
+class MermaidValidator:
+    """Validates Mermaid ERD syntax using the Mermaid CLI."""
+
+    def __init__(self):
+        self.mermaid_cli_available = self._check_mermaid_cli()
+
+    def _check_mermaid_cli(self) -> bool:
+        """Check if Mermaid CLI is available."""
+        try:
+            result = subprocess.run(
+                ["mmdc", "--version"], 
+                capture_output=True, 
+                text=True, 
+                timeout=10
+            )
+            return result.returncode == 0
+        except (subprocess.TimeoutExpired, FileNotFoundError, subprocess.SubprocessError):
+            return False
+
+    def validate_mermaid_syntax(self, mermaid_content: str) -> ValidationResult:
+        """Validate Mermaid ERD syntax."""
+        result = ValidationResult(is_valid=True)
+        
+        if not self.mermaid_cli_available:
+            result.add_warning(
+                ValidationError(
+                    message="Mermaid CLI not available - syntax validation skipped",
+                    severity=ErrorSeverity.INFO,
+                    error_code="MERMAID_CLI_UNAVAILABLE"
+                )
+            )
+            return result
+        
+        try:
+            # Create temporary file with Mermaid content
+            with tempfile.NamedTemporaryFile(mode='w', suffix='.mmd', delete=False) as f:
+                f.write(mermaid_content)
+                temp_file = f.name
+            
+            try:
+                # Validate syntax using Mermaid CLI
+                validation_result = subprocess.run(
+                    ["mmdc", "-i", temp_file, "-o", "/dev/null"],
+                    capture_output=True,
+                    text=True,
+                    timeout=30
+                )
+                
+                if validation_result.returncode != 0:
+                    # Parse error output
+                    error_lines = validation_result.stderr.split('\n')
+                    for line in error_lines:
+                        if line.strip() and "error" in line.lower():
+                            result.add_error(
+                                ValidationError(
+                                    message=f"Mermaid syntax error: {line.strip()}",
+                                    severity=ErrorSeverity.CRITICAL,
+                                    error_code="MERMAID_SYNTAX_ERROR"
+                                )
+                            )
+                else:
+                    # Syntax is valid
+                    result.add_warning(
+                        ValidationError(
+                            message="Mermaid syntax validation passed",
+                            severity=ErrorSeverity.INFO,
+                            error_code="MERMAID_SYNTAX_VALID"
+                        )
+                    )
+                    
+            finally:
+                # Clean up temporary file
+                Path(temp_file).unlink(missing_ok=True)
+                
+        except subprocess.TimeoutExpired:
+            result.add_error(
+                ValidationError(
+                    message="Mermaid syntax validation timed out",
+                    severity=ErrorSeverity.CRITICAL,
+                    error_code="MERMAID_TIMEOUT"
+                )
+            )
+        except Exception as e:
+            result.add_error(
+                ValidationError(
+                    message=f"Mermaid syntax validation failed: {str(e)}",
+                    severity=ErrorSeverity.CRITICAL,
+                    error_code="MERMAID_VALIDATION_ERROR"
+                )
+            )
+        
+        return result
+
+    def validate_erd_structure(self, mermaid_content: str) -> ValidationResult:
+        """Validate ERD structure and content."""
+        result = ValidationResult(is_valid=True)
+        
+        lines = mermaid_content.split('\n')
+        
+        # Check for erDiagram declaration
+        if not any('erDiagram' in line for line in lines):
+            result.add_error(
+                ValidationError(
+                    message="Missing erDiagram declaration",
+                    severity=ErrorSeverity.CRITICAL,
+                    error_code="MISSING_ERDIAGRAM"
+                )
+            )
+        
+        # Check for entities
+        entity_count = 0
+        for line in lines:
+            if line.strip().endswith('{') and not line.strip().startswith('%'):
+                entity_count += 1
+        
+        if entity_count == 0:
+            result.add_error(
+                ValidationError(
+                    message="No entities found in ERD",
+                    severity=ErrorSeverity.CRITICAL,
+                    error_code="NO_ENTITIES"
+                )
+            )
+        
+        # Check for relationships
+        relationship_count = 0
+        for line in lines:
+            if '--' in line and not line.strip().startswith('%'):
+                relationship_count += 1
+        
+        # Check for common syntax issues
+        for i, line in enumerate(lines):
+            line_num = i + 1
+            
+            # Check for unclosed braces
+            if '{' in line and not line.strip().endswith('{'):
+                if line.count('{') != line.count('}'):
+                    result.add_error(
+                        ValidationError(
+                            message=f"Unmatched braces on line {line_num}",
+                            severity=ErrorSeverity.CRITICAL,
+                            line_number=line_num,
+                            error_code="UNMATCHED_BRACES"
+                        )
+                    )
+            
+            # Check for invalid relationship syntax
+            if '--' in line and not line.strip().startswith('%'):
+                if not any(symbol in line for symbol in ['||', '|o', '}o', '}|']):
+                    result.add_error(
+                        ValidationError(
+                            message=f"Invalid relationship syntax on line {line_num}",
+                            severity=ErrorSeverity.CRITICAL,
+                            line_number=line_num,
+                            error_code="INVALID_RELATIONSHIP_SYNTAX"
+                        )
+                    )
+        
+        # Add summary info
+        result.add_warning(
+            ValidationError(
+                message=f"ERD contains {entity_count} entities and {relationship_count} relationships",
+                severity=ErrorSeverity.INFO,
+                error_code="ERD_SUMMARY"
+            )
+        )
+        
+        return result
+
+    def validate_complete(self, mermaid_content: str) -> ValidationResult:
+        """Perform complete Mermaid ERD validation."""
+        result = ValidationResult(is_valid=True)
+        
+        # Structure validation
+        structure_result = self.validate_erd_structure(mermaid_content)
+        result.errors.extend(structure_result.errors)
+        result.warnings.extend(structure_result.warnings)
+        if not structure_result.is_valid:
+            result.is_valid = False
+        
+        # Syntax validation (only if structure is valid)
+        if structure_result.is_valid:
+            syntax_result = self.validate_mermaid_syntax(mermaid_content)
+            result.errors.extend(syntax_result.errors)
+            result.warnings.extend(syntax_result.warnings)
+            if not syntax_result.is_valid:
+                result.is_valid = False
+        
+        return result
\ No newline at end of file
diff --git a/backend/erd/models.py b/backend/erd/models.py
new file mode 100644
index 0000000000..f773cbd748
--- /dev/null
+++ b/backend/erd/models.py
@@ -0,0 +1,144 @@
+"""
+Model Metadata entity for ERD generation.
+Extracted metadata from SQLModel classes for ERD generation.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class FieldMetadata:
+    """Metadata for a single field in a SQLModel."""
+
+    name: str
+    type_hint: str
+    is_primary_key: bool = False
+    is_foreign_key: bool = False
+    is_nullable: bool = True
+    default_value: Any | None = None
+    constraints: list[str] = None
+    foreign_key_reference: str | None = None
+
+    def __post_init__(self):
+        if self.constraints is None:
+            self.constraints = []
+
+
+@dataclass
+class RelationshipMetadata:
+    """Metadata for relationships between SQLModel classes."""
+
+    field_name: str
+    target_model: str
+    relationship_type: str  # "one-to-one", "one-to-many", "many-to-many"
+    foreign_key_field: str | None = None
+    back_populates: str | None = None
+    cascade: str | None = None
+
+
+@dataclass
+class ConstraintMetadata:
+    """Metadata for database constraints."""
+
+    name: str
+    type: str  # "primary_key", "foreign_key", "unique", "check"
+    fields: list[str]
+    target_table: str | None = None
+    target_fields: list[str] | None = None
+
+
+@dataclass
+class ModelMetadata:
+    """Extracted metadata from SQLModel classes for ERD generation."""
+
+    class_name: str
+    table_name: str
+    file_path: Path
+    line_number: int
+    fields: list[FieldMetadata]
+    relationships: list[RelationshipMetadata]
+    constraints: list[ConstraintMetadata]
+    primary_key: str | None = None
+    imports: list[str] = None
+
+    def __post_init__(self):
+        if self.imports is None:
+            self.imports = []
+
+        # Auto-detect primary key from fields
+        if not self.primary_key:
+            for field in self.fields:
+                if field.is_primary_key:
+                    self.primary_key = field.name
+                    break
+
+    @property
+    def has_foreign_keys(self) -> bool:
+        """Check if this model has any foreign key relationships."""
+        return any(field.is_foreign_key for field in self.fields)
+
+    @property
+    def foreign_key_fields(self) -> list[FieldMetadata]:
+        """Get all foreign key fields in this model."""
+        return [field for field in self.fields if field.is_foreign_key]
+
+    @property
+    def entity_name(self) -> str:
+        """Get the entity name for ERD (uppercase table name)."""
+        return self.table_name.upper()
+
+    def get_field_by_name(self, field_name: str) -> FieldMetadata | None:
+        """Get a field by its name."""
+        for field in self.fields:
+            if field.name == field_name:
+                return field
+        return None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert model metadata to dictionary for serialization."""
+        return {
+            "class_name": self.class_name,
+            "table_name": self.table_name,
+            "file_path": str(self.file_path),
+            "line_number": self.line_number,
+            "fields": [
+                {
+                    "name": f.name,
+                    "type_hint": f.type_hint,
+                    "is_primary_key": f.is_primary_key,
+                    "is_foreign_key": f.is_foreign_key,
+                    "is_nullable": f.is_nullable,
+                    "default_value": (
+                        str(f.default_value) if f.default_value is not None else None
+                    ),
+                    "constraints": f.constraints,
+                    "foreign_key_reference": f.foreign_key_reference,
+                }
+                for f in self.fields
+            ],
+            "relationships": [
+                {
+                    "field_name": r.field_name,
+                    "target_model": r.target_model,
+                    "relationship_type": r.relationship_type,
+                    "foreign_key_field": r.foreign_key_field,
+                    "back_populates": r.back_populates,
+                    "cascade": r.cascade,
+                }
+                for r in self.relationships
+            ],
+            "constraints": [
+                {
+                    "name": c.name,
+                    "type": c.type,
+                    "fields": c.fields,
+                    "target_table": c.target_table,
+                    "target_fields": c.target_fields,
+                }
+                for c in self.constraints
+            ],
+            "primary_key": self.primary_key,
+            "imports": self.imports,
+        }
diff --git a/backend/erd/output.py b/backend/erd/output.py
new file mode 100644
index 0000000000..c331e774ec
--- /dev/null
+++ b/backend/erd/output.py
@@ -0,0 +1,191 @@
+"""
+ERD Output entity for generated Mermaid ERD diagram structure.
+"""
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Any
+
+
+@dataclass
+class ERDOutput:
+    """Generated Mermaid ERD diagram structure."""
+
+    mermaid_code: str
+    entities: list[dict[str, Any]]
+    relationships: list[dict[str, Any]]
+    metadata: dict[str, Any] = field(default_factory=dict)
+    validation_status: str = "pending"  # "pending", "valid", "invalid", "error"
+    generation_timestamp: datetime | None = None
+    version: str = "1.0"
+
+    def __post_init__(self):
+        if self.generation_timestamp is None:
+            self.generation_timestamp = datetime.now()
+
+        # Initialize metadata if empty
+        if not self.metadata:
+            self.metadata = {
+                "generated_at": self.generation_timestamp.isoformat(),
+                "version": self.version,
+                "entity_count": len(self.entities),
+                "relationship_count": len(self.relationships),
+            }
+
+    @property
+    def is_valid(self) -> bool:
+        """Check if the ERD output is valid."""
+        return self.validation_status == "valid"
+
+    @property
+    def has_errors(self) -> bool:
+        """Check if the ERD output has errors."""
+        return self.validation_status in ["invalid", "error"]
+
+    def mark_as_valid(self) -> None:
+        """Mark the ERD output as valid."""
+        self.validation_status = "valid"
+
+    def mark_as_invalid(self, reason: str = None) -> None:
+        """Mark the ERD output as invalid."""
+        self.validation_status = "invalid"
+        if reason:
+            self.metadata["validation_error"] = reason
+
+    def mark_as_error(self, error_message: str) -> None:
+        """Mark the ERD output as having an error."""
+        self.validation_status = "error"
+        self.metadata["error_message"] = error_message
+
+    def add_entity(self, entity: dict[str, Any]) -> None:
+        """Add an entity to the ERD output."""
+        self.entities.append(entity)
+        self.metadata["entity_count"] = len(self.entities)
+
+    def add_relationship(self, relationship: dict[str, Any]) -> None:
+        """Add a relationship to the ERD output."""
+        self.relationships.append(relationship)
+        self.metadata["relationship_count"] = len(self.relationships)
+
+    def get_entity_by_name(self, entity_name: str) -> dict[str, Any] | None:
+        """Get an entity by its name."""
+        for entity in self.entities:
+            if entity.get("name") == entity_name:
+                return entity
+        return None
+
+    def get_relationships_for_entity(self, entity_name: str) -> list[dict[str, Any]]:
+        """Get all relationships involving a specific entity."""
+        relationships = []
+        for rel in self.relationships:
+            if (
+                rel.get("from_entity") == entity_name
+                or rel.get("to_entity") == entity_name
+            ):
+                relationships.append(rel)
+        return relationships
+
+    def to_markdown(self, include_metadata: bool = True) -> str:
+        """Convert ERD output to Markdown format."""
+        lines = ["# Database ERD Diagram", ""]
+
+        if include_metadata:
+            lines.extend(
+                [
+                    "## Metadata",
+                    f"- **Generated**: {self.metadata.get('generated_at', 'Unknown')}",
+                    f"- **Version**: {self.metadata.get('version', 'Unknown')}",
+                    f"- **Entities**: {self.metadata.get('entity_count', 0)}",
+                    f"- **Relationships**: {self.metadata.get('relationship_count', 0)}",
+                    f"- **Status**: {self.validation_status}",
+                    "",
+                ]
+            )
+
+        lines.extend(
+            [
+                "## Entity Relationship Diagram",
+                "",
+                "```mermaid",
+                self.mermaid_code,
+                "```",
+                "",
+                "*This diagram is automatically generated from SQLModel definitions*",
+            ]
+        )
+
+        if self.has_errors and "error_message" in self.metadata:
+            lines.extend(
+                [
+                    "",
+                    "## Errors",
+                    "",
+                    f"⚠️ **Error**: {self.metadata['error_message']}",
+                ]
+            )
+
+        return "\n".join(lines)
+
+    def to_mermaid_format(self, include_metadata: bool = True) -> str:
+        """Convert ERD output to pure Mermaid format with metadata as comments."""
+        lines = []
+        
+        if include_metadata:
+               lines.extend([
+                   "%% Database ERD Diagram",
+                   f"%% Generated: {self.metadata.get('generated_at', 'Unknown')}",
+                   f"%% Version: {self.metadata.get('version', 'Unknown')}",
+                   f"%% Entities: {len(self.entities)}",
+                   f"%% Relationships: {len(self.relationships)}",
+                   f"%% Status: {self.validation_status}",
+                   ""
+               ])
+            
+               if self.has_errors and "error_message" in self.metadata:
+                   lines.extend([
+                       f"%% Error: {self.metadata['error_message']}",
+                       ""
+                   ])
+               
+               lines.extend([
+                   "%% This diagram is automatically generated from SQLModel definitions",
+                   ""
+               ])
+        
+        # Add the actual Mermaid diagram
+        lines.append(self.mermaid_code)
+        
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert ERD output to dictionary for serialization."""
+        return {
+            "mermaid_code": self.mermaid_code,
+            "entities": self.entities,
+            "relationships": self.relationships,
+            "metadata": self.metadata,
+            "validation_status": self.validation_status,
+            "generation_timestamp": (
+                self.generation_timestamp.isoformat()
+                if self.generation_timestamp
+                else None
+            ),
+            "version": self.version,
+        }
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ERDOutput":
+        """Create ERDOutput from dictionary."""
+        timestamp = None
+        if data.get("generation_timestamp"):
+            timestamp = datetime.fromisoformat(data["generation_timestamp"])
+
+        return cls(
+            mermaid_code=data["mermaid_code"],
+            entities=data["entities"],
+            relationships=data["relationships"],
+            metadata=data.get("metadata", {}),
+            validation_status=data.get("validation_status", "pending"),
+            generation_timestamp=timestamp,
+            version=data.get("version", "1.0"),
+        )
diff --git a/backend/erd/relationships.py b/backend/erd/relationships.py
new file mode 100644
index 0000000000..7c7578e442
--- /dev/null
+++ b/backend/erd/relationships.py
@@ -0,0 +1,242 @@
+"""
+Relationship Definition entity for relationships between entities in ERD.
+"""
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class RelationshipType(Enum):
+    """Enumeration of relationship types."""
+
+    ONE_TO_ONE = "1:1"
+    ONE_TO_MANY = "1:N"
+    MANY_TO_ONE = "N:1"
+    MANY_TO_MANY = "N:N"
+
+
+class Cardinality(Enum):
+    """Enumeration of cardinality symbols for Mermaid ERD."""
+
+    ONE = "||"
+    ZERO_OR_ONE = "|o"
+    ZERO_OR_MORE = "}o"
+    ONE_OR_MORE = "}|"
+
+
+@dataclass
+class RelationshipDefinition:
+    """Definition of relationships between entities in ERD."""
+
+    from_entity: str
+    to_entity: str
+    relationship_type: RelationshipType
+    from_cardinality: Cardinality
+    to_cardinality: Cardinality
+    label: str | None = None
+    foreign_key_field: str | None = None
+    foreign_key_target_field: str | None = None
+    cascade_delete: bool = False
+    cascade_update: bool = False
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self):
+        """Ensure entity names are uppercase."""
+        self.from_entity = self.from_entity.upper()
+        self.to_entity = self.to_entity.upper()
+
+        # Generate label if not provided
+        if not self.label:
+            self.label = f"{self.from_entity} -> {self.to_entity}"
+
+    @property
+    def mermaid_cardinality(self) -> str:
+        """Get Mermaid cardinality representation."""
+        return f"{self.from_cardinality.value}--{self.to_cardinality.value}"
+
+    def to_mermaid_relationship(self) -> str:
+        """Convert relationship to Mermaid ERD relationship syntax."""
+        # Build relationship line with proper cardinality symbols
+        cardinality_map = {
+            Cardinality.ONE: "||",
+            Cardinality.ZERO_OR_ONE: "|o", 
+            Cardinality.ZERO_OR_MORE: "o{",
+            Cardinality.ONE_OR_MORE: "}|",
+        }
+        
+        from_symbol = cardinality_map.get(self.from_cardinality, "||")
+        to_symbol = cardinality_map.get(self.to_cardinality, "||")
+        
+        # Create relationship line
+        relationship_line = f"{self.from_entity} {from_symbol}--{to_symbol} {self.to_entity}"
+        
+        # Add label if present
+        if self.label:
+            relationship_line += f" : {self.label}"
+        
+        return relationship_line
+
+    def is_bidirectional(self) -> bool:
+        """Check if this is a bidirectional relationship."""
+        # Check if there's a corresponding reverse relationship
+        # This would be determined by the metadata or by analyzing the model
+        return self.metadata.get("is_bidirectional", False)
+
+    def get_foreign_key_info(self) -> dict[str, str]:
+        """Get foreign key information."""
+        return {
+            "field": self.foreign_key_field or "",
+            "target_field": self.foreign_key_target_field or "",
+            "target_table": self.to_entity,
+        }
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert relationship definition to dictionary."""
+        return {
+            "from_entity": self.from_entity,
+            "to_entity": self.to_entity,
+            "relationship_type": self.relationship_type.value,
+            "from_cardinality": self.from_cardinality.value,
+            "to_cardinality": self.to_cardinality.value,
+            "label": self.label,
+            "foreign_key_field": self.foreign_key_field,
+            "foreign_key_target_field": self.foreign_key_target_field,
+            "cascade_delete": self.cascade_delete,
+            "cascade_update": self.cascade_update,
+            "metadata": self.metadata,
+        }
+
+    @classmethod
+    def from_model_relationship(
+        cls, relationship_metadata, from_model, to_model
+    ) -> "RelationshipDefinition":
+        """Create RelationshipDefinition from ModelMetadata relationship."""
+
+        # Determine relationship type based on metadata
+        rel_type_str = relationship_metadata.relationship_type.lower()
+
+        if rel_type_str == "one-to-one":
+            relationship_type = RelationshipType.ONE_TO_ONE
+            from_cardinality = Cardinality.ONE
+            to_cardinality = Cardinality.ONE
+        elif rel_type_str == "one-to-many":
+            relationship_type = RelationshipType.ONE_TO_MANY
+            from_cardinality = Cardinality.ONE
+            to_cardinality = Cardinality.ZERO_OR_MORE
+        elif rel_type_str == "many-to-one":
+            relationship_type = RelationshipType.MANY_TO_ONE
+            from_cardinality = Cardinality.ZERO_OR_MORE
+            to_cardinality = Cardinality.ONE
+        elif rel_type_str == "many-to-many":
+            relationship_type = RelationshipType.MANY_TO_MANY
+            from_cardinality = Cardinality.ZERO_OR_MORE
+            to_cardinality = Cardinality.ZERO_OR_MORE
+        else:
+            # Default to one-to-many
+            relationship_type = RelationshipType.ONE_TO_MANY
+            from_cardinality = Cardinality.ONE
+            to_cardinality = Cardinality.ZERO_OR_MORE
+
+        # Create a simple label (just the field name)
+        label = relationship_metadata.field_name
+
+        return cls(
+            from_entity=from_model.table_name,
+            to_entity=to_model.table_name,
+            relationship_type=relationship_type,
+            from_cardinality=from_cardinality,
+            to_cardinality=to_cardinality,
+            label=label,
+            foreign_key_field=relationship_metadata.foreign_key_field,
+            cascade_delete=relationship_metadata.cascade,
+            metadata={
+                "field_name": relationship_metadata.field_name,
+                "target_model": relationship_metadata.target_model,
+                "back_populates": relationship_metadata.back_populates,
+                "cascade": relationship_metadata.cascade,
+                "is_bidirectional": relationship_metadata.back_populates is not None,
+            },
+        )
+
+    @classmethod
+    def from_foreign_key(
+        cls, from_model, to_model, foreign_key_field
+    ) -> "RelationshipDefinition":
+        """Create RelationshipDefinition from foreign key relationship."""
+
+        # This is typically a many-to-one relationship
+        relationship_type = RelationshipType.MANY_TO_ONE
+        from_cardinality = Cardinality.ZERO_OR_MORE
+        to_cardinality = Cardinality.ONE
+
+        return cls(
+            from_entity=from_model.table_name,
+            to_entity=to_model.table_name,
+            relationship_type=relationship_type,
+            from_cardinality=from_cardinality,
+            to_cardinality=to_cardinality,
+            label=foreign_key_field.name,
+            foreign_key_field=foreign_key_field.name,
+            foreign_key_target_field=to_model.primary_key,
+            metadata={
+                "inferred_from_fk": True,
+                "field_name": foreign_key_field.name,
+            },
+        )
+
+
+@dataclass
+class RelationshipManager:
+    """Manager for handling relationships between entities."""
+
+    relationships: list[RelationshipDefinition] = field(default_factory=list)
+
+    def add_relationship(self, relationship: RelationshipDefinition) -> None:
+        """Add a relationship to the manager."""
+        self.relationships.append(relationship)
+
+    def get_relationships_for_entity(
+        self, entity_name: str
+    ) -> list[RelationshipDefinition]:
+        """Get all relationships involving a specific entity."""
+        entity_name = entity_name.upper()
+        return [
+            rel
+            for rel in self.relationships
+            if rel.from_entity == entity_name or rel.to_entity == entity_name
+        ]
+
+    def get_outgoing_relationships(
+        self, entity_name: str
+    ) -> list[RelationshipDefinition]:
+        """Get relationships where the entity is the source."""
+        entity_name = entity_name.upper()
+        return [rel for rel in self.relationships if rel.from_entity == entity_name]
+
+    def get_incoming_relationships(
+        self, entity_name: str
+    ) -> list[RelationshipDefinition]:
+        """Get relationships where the entity is the target."""
+        entity_name = entity_name.upper()
+        return [rel for rel in self.relationships if rel.to_entity == entity_name]
+
+    def has_relationship(self, from_entity: str, to_entity: str) -> bool:
+        """Check if there's a relationship between two entities."""
+        from_entity = from_entity.upper()
+        to_entity = to_entity.upper()
+        return any(
+            (rel.from_entity == from_entity and rel.to_entity == to_entity)
+            or (rel.from_entity == to_entity and rel.to_entity == from_entity)
+            for rel in self.relationships
+        )
+
+    def to_mermaid_relationships(self) -> list[str]:
+        """Convert all relationships to Mermaid ERD syntax."""
+        return [rel.to_mermaid_relationship() for rel in self.relationships]
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert relationship manager to dictionary."""
+        return {
+            "relationships": [rel.to_dict() for rel in self.relationships],
+        }
diff --git a/backend/erd/validation.py b/backend/erd/validation.py
new file mode 100644
index 0000000000..b8f8b7c817
--- /dev/null
+++ b/backend/erd/validation.py
@@ -0,0 +1,345 @@
+"""
+ERD Validation System - Validate that generated ERD diagrams accurately represent current SQLModel definitions.
+"""
+
+import re
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+
+class ErrorSeverity(Enum):
+    """Enumeration of validation error severity levels."""
+
+    CRITICAL = "critical"
+    WARNING = "warning"
+    INFO = "info"
+
+
+class ValidationMode(Enum):
+    """Enumeration of validation modes."""
+
+    STRICT = "strict"
+    PERMISSIVE = "permissive"
+    REPORT = "report"
+
+
+@dataclass
+class ValidationError:
+    """Individual validation error."""
+
+    message: str
+    severity: ErrorSeverity
+    line_number: int | None = None
+    field_name: str | None = None
+    entity_name: str | None = None
+    error_code: str | None = None
+    suggestions: list[str] = field(default_factory=list)
+
+    def __post_init__(self):
+        if self.line_number is None:
+            self.line_number = -1
+
+
+@dataclass
+class ValidationResult:
+    """Result of ERD validation."""
+
+    is_valid: bool
+    errors: list[ValidationError] = field(default_factory=list)
+    warnings: list[ValidationError] = field(default_factory=list)
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    def add_error(self, error: ValidationError) -> None:
+        """Add a validation error."""
+        self.errors.append(error)
+        if error.severity == ErrorSeverity.CRITICAL:
+            self.is_valid = False
+
+    def add_warning(self, warning: ValidationError) -> None:
+        """Add a validation warning."""
+        self.warnings.append(warning)
+
+    def has_critical_errors(self) -> bool:
+        """Check if there are any critical errors."""
+        return any(error.severity == ErrorSeverity.CRITICAL for error in self.errors)
+
+
+@dataclass
+class ValidationConfig:
+    """Configuration for ERD validation."""
+
+    strict_mode: bool = True
+    check_syntax: bool = True
+    validate_relationships: bool = True
+    validate_constraints: bool = True
+    max_errors: int = 10
+    timeout_seconds: int = 30
+
+
+class ERDValidator:
+    """Main ERD validation system."""
+
+    def __init__(self, config: ValidationConfig | None = None):
+        self.config = config or ValidationConfig()
+        self.mode = (
+            ValidationMode.STRICT
+            if self.config.strict_mode
+            else ValidationMode.PERMISSIVE
+        )
+
+    def set_mode(self, mode: ValidationMode) -> None:
+        """Set validation mode."""
+        self.mode = mode
+
+    def validate_all(self, erd_content: str) -> ValidationResult:
+        """Validate all aspects of an ERD."""
+        result = ValidationResult(is_valid=True)
+
+        try:
+            # Parse entities and relationships for validation
+            entities = self._parse_entities(erd_content)
+            relationships = self._parse_relationships(erd_content)
+
+            # Validate entities exist
+            entities_result = self.validate_entities_exist(erd_content)
+            result.errors.extend(entities_result.errors)
+            result.warnings.extend(entities_result.warnings)
+
+            # Validate relationships
+            if self.config.validate_relationships:
+                relationships_result = self.validate_relationships(relationships)
+                result.errors.extend(relationships_result.errors)
+                result.warnings.extend(relationships_result.warnings)
+
+            # Update overall validity
+            result.is_valid = not result.has_critical_errors()
+
+        except Exception as e:
+            error = ValidationError(
+                message=f"Validation failed: {str(e)}",
+                severity=ErrorSeverity.CRITICAL,
+                error_code="VALIDATION_ERROR",
+            )
+            result.add_error(error)
+
+        return result
+
+    def validate_mermaid_syntax(self, erd_content: str) -> ValidationResult:
+        """Validate Mermaid ERD syntax."""
+        result = ValidationResult(is_valid=True)
+
+        # Check for basic Mermaid ERD structure
+        if "erDiagram" not in erd_content:
+            error = ValidationError(
+                message="Missing 'erDiagram' declaration",
+                severity=ErrorSeverity.CRITICAL,
+                error_code="MISSING_ERDIAGRAM",
+            )
+            result.add_error(error)
+
+        # Check for valid entity syntax
+        entity_pattern = r"^\s*[A-Z_][A-Z0-9_]*\s*\{"
+        lines = erd_content.split("\n")
+
+        for i, line in enumerate(lines, 1):
+            if (
+                line.strip()
+                and not line.strip().startswith("erDiagram")
+                and not line.strip().startswith("}")
+            ):
+                if not re.match(entity_pattern, line.strip()) and "--" not in line:
+                    if line.strip().startswith("```"):
+                        continue  # Skip markdown code blocks
+
+                    warning = ValidationError(
+                        message=f"Potentially invalid ERD syntax on line {i}: {line.strip()}",
+                        severity=ErrorSeverity.WARNING,
+                        line_number=i,
+                        error_code="INVALID_SYNTAX",
+                    )
+                    result.add_warning(warning)
+
+        return result
+
+    def validate_entities(self, erd_content: str) -> ValidationResult:
+        """Validate entity completeness and accuracy."""
+        result = ValidationResult(is_valid=True)
+
+        # Parse entities from ERD content
+        entities = self._parse_entities(erd_content)
+
+        if not entities:
+            error = ValidationError(
+                message="No entities found in ERD",
+                severity=ErrorSeverity.CRITICAL,
+                error_code="NO_ENTITIES",
+            )
+            result.add_error(error)
+
+        # Validate each entity
+        for entity in entities:
+            if not entity.get("fields"):
+                error = ValidationError(
+                    message=f"Entity {entity.get('name', 'Unknown')} has no fields",
+                    severity=ErrorSeverity.WARNING,
+                    entity_name=entity.get("name"),
+                    error_code="ENTITY_NO_FIELDS",
+                )
+                result.add_warning(error)
+
+            # Check for primary key
+            has_primary_key = any(
+                "PK" in field.get("constraints", "")
+                for field in entity.get("fields", [])
+            )
+            if not has_primary_key:
+                warning = ValidationError(
+                    message=f"Entity {entity.get('name', 'Unknown')} has no primary key",
+                    severity=ErrorSeverity.WARNING,
+                    entity_name=entity.get("name"),
+                    error_code="ENTITY_NO_PK",
+                )
+                result.add_warning(warning)
+
+        return result
+
+    def validate_relationships(
+        self, relationships: list[dict[str, Any]]
+    ) -> ValidationResult:
+        """Validate relationship cardinality and constraints."""
+        result = ValidationResult(is_valid=True)
+
+        for rel in relationships:
+            # Basic relationship validation
+            if not rel.get("from_entity") or not rel.get("to_entity"):
+                error = ValidationError(
+                    message="Invalid relationship: missing from_entity or to_entity",
+                    severity=ErrorSeverity.CRITICAL,
+                    error_code="INVALID_RELATIONSHIP",
+                )
+                result.add_error(error)
+
+        return result
+
+    def validate_fields(self, test_data: dict[str, Any]) -> ValidationResult:
+        """Validate field definitions and types."""
+        result = ValidationResult(is_valid=True)
+
+        entities = test_data.get("entities", [])
+
+        # Simple field validation - check if field names match
+        for entity in entities:
+            _ = {field["name"] for field in entity.get("fields", [])}
+            # This would be expanded with actual model comparison
+
+        return result
+
+    def validate_primary_keys(self, entities: list[dict[str, Any]]) -> ValidationResult:
+        """Validate primary key definitions."""
+        result = ValidationResult(is_valid=True)
+
+        for entity in entities:
+            primary_key = entity.get("primary_key")
+            if not primary_key:
+                error = ValidationError(
+                    message=f"Entity {entity.get('name')} has no primary key",
+                    severity=ErrorSeverity.WARNING,
+                    entity_name=entity.get("name"),
+                    error_code="NO_PRIMARY_KEY",
+                )
+                result.add_warning(error)
+
+        return result
+
+    def validate_foreign_keys(
+        self, foreign_keys: list[dict[str, Any]]
+    ) -> ValidationResult:
+        """Validate foreign key relationships."""
+        result = ValidationResult(is_valid=True)
+
+        for fk in foreign_keys:
+            if not fk.get("references"):
+                error = ValidationError(
+                    message=f"Foreign key {fk.get('field')} has no reference",
+                    severity=ErrorSeverity.CRITICAL,
+                    field_name=fk.get("field"),
+                    error_code="FK_NO_REFERENCE",
+                )
+                result.add_error(error)
+
+        return result
+
+    def _parse_entities(self, erd_content: str) -> list[dict[str, Any]]:
+        """Parse entities from ERD content."""
+        entities = []
+        lines = erd_content.split("\n")
+        current_entity = None
+
+        for line in lines:
+            line = line.strip()
+
+            # Start of entity
+            if line.endswith("{"):
+                entity_name = line[:-1].strip()
+                current_entity = {"name": entity_name, "fields": []}
+                entities.append(current_entity)
+
+            # Field in entity
+            elif current_entity and line and not line.startswith("}"):
+                field_parts = line.split()
+                if len(field_parts) >= 2:
+                    field = {
+                        "type": field_parts[0],
+                        "name": field_parts[1],
+                        "constraints": (
+                            " ".join(field_parts[2:]) if len(field_parts) > 2 else ""
+                        ),
+                    }
+                    current_entity["fields"].append(field)
+
+            # End of entity
+            elif line == "}":
+                current_entity = None
+
+        return entities
+
+    def _parse_relationships(self, erd_content: str) -> list[dict[str, Any]]:
+        """Parse relationships from ERD content."""
+        relationships = []
+        lines = erd_content.split("\n")
+
+        for line in lines:
+            line = line.strip()
+
+            # Relationship line (contains --)
+            if "--" in line and not line.startswith("erDiagram"):
+                parts = line.split("--")
+                if len(parts) >= 2:
+                    from_part = parts[0].strip()
+                    to_part = parts[1].strip()
+
+                    # Parse cardinality and labels
+                    from_entity = from_part.split()[0] if from_part.split() else ""
+                    to_entity = to_part.split()[0] if to_part.split() else ""
+
+                    relationship = {
+                        "from_entity": from_entity,
+                        "to_entity": to_entity,
+                        "cardinality": line,
+                    }
+                    relationships.append(relationship)
+
+        return relationships
+
+    def validate_for_cli(self, erd_content: str) -> ValidationResult:
+        """Validate ERD for CLI usage."""
+        return self.validate_all(erd_content)
+
+    def validate_for_pre_commit(self, erd_content: str) -> ValidationResult:
+        """Validate ERD for pre-commit hook usage."""
+        return self.validate_all(erd_content)
+
+    def validate_for_ci_cd(self, erd_content: str) -> ValidationResult:
+        """Validate ERD for CI/CD usage."""
+        return self.validate_all(erd_content)
diff --git a/backend/pyproject.toml b/backend/pyproject.toml
index d72454c28a..73c1e6aefc 100644
--- a/backend/pyproject.toml
+++ b/backend/pyproject.toml
@@ -15,7 +15,7 @@ dependencies = [
     "alembic<2.0.0,>=1.12.1",
     "httpx<1.0.0,>=0.25.1",
     "psycopg[binary]<4.0.0,>=3.1.13",
-    "sqlmodel<1.0.0,>=0.0.21",
+    "sqlmodel>=0.0.21,<1.0.0",
     # Pin bcrypt until passlib supports the latest
     "bcrypt==4.3.0",
     "pydantic-settings<3.0.0,>=2.2.1",
@@ -25,12 +25,14 @@ dependencies = [
 
 [tool.uv]
 dev-dependencies = [
-    "pytest<8.0.0,>=7.4.3",
+    "pytest>=7.4.3,<8.0.0",
     "mypy<2.0.0,>=1.8.0",
-    "ruff<1.0.0,>=0.2.2",
-    "pre-commit<4.0.0,>=3.6.2",
+    "ruff>=0.2.2,<1.0.0",
+    "pre-commit>=3.6.2,<4.0.0",
     "types-passlib<2.0.0.0,>=1.7.7.20240106",
     "coverage<8.0.0,>=7.4.3",
+    "pytest-cov>=6.3.0",
+    "black>=25.9.0",
 ]
 
 [build-system]
diff --git a/backend/scripts/generate_erd.py b/backend/scripts/generate_erd.py
new file mode 100755
index 0000000000..ad89d15a4d
--- /dev/null
+++ b/backend/scripts/generate_erd.py
@@ -0,0 +1,175 @@
+#!/usr/bin/env python3
+"""
+CLI script for ERD generation.
+"""
+
+import argparse
+import sys
+import time
+from pathlib import Path
+
+# Add the backend directory to the Python path
+backend_dir = Path(__file__).parent.parent
+sys.path.insert(0, str(backend_dir))
+
+from erd import ERDGenerator
+
+
+def main():
+    """Main CLI entry point for ERD generation."""
+    parser = argparse.ArgumentParser(description="Generate Mermaid ERD diagrams from SQLModel definitions")
+    parser.add_argument("--models-path", default="app/models.py", help="Path to SQLModel definitions")
+    parser.add_argument("--output-path", default="../docs/database/erd.mmd", help="Path for generated ERD documentation")
+    parser.add_argument("--validate", action="store_true", help="Run validation checks on generated ERD")
+    parser.add_argument("--verbose", action="store_true", help="Enable verbose output")
+    parser.add_argument("--force", action="store_true", help="Force overwrite of existing output file")
+    parser.add_argument("--backup", action="store_true", help="Create backup of existing ERD file before overwriting")
+
+    args = parser.parse_args()
+
+    try:
+        # Enhanced file system operations
+        if not _validate_input_path(args.models_path):
+            print(f"Invalid models path: {args.models_path}", file=sys.stderr)
+            return 2
+
+        if not _prepare_output_path(args.output_path, args.force, args.backup):
+            print(f"Failed to prepare output path: {args.output_path}", file=sys.stderr)
+            return 3
+
+        # Initialize ERD generator
+        generator = ERDGenerator(
+            models_path=args.models_path,
+            output_path=args.output_path
+        )
+
+        if args.verbose:
+            print(f"Models path: {args.models_path}")
+            print(f"Output path: {args.output_path}")
+            print("Starting ERD generation...")
+
+        # Validate models if requested
+        if args.validate:
+            if args.verbose:
+                print("Validating models...")
+            validation_result = _validate_models(generator, args.verbose)
+            if not validation_result:
+                return 2
+
+        # Generate ERD
+        mermaid_code = generator.generate_erd()
+
+        if args.verbose:
+            print("ERD generation completed successfully")
+            print(f"Generated {len(mermaid_code.splitlines())} lines of Mermaid code")
+            _print_output_summary(args.output_path)
+
+        return 0
+
+    except FileNotFoundError as e:
+        print(f"File not found: {e}", file=sys.stderr)
+        return 2
+    except PermissionError as e:
+        print(f"Permission denied: {e}", file=sys.stderr)
+        return 3
+    except Exception as e:
+        print(f"ERD generation failed: {e}", file=sys.stderr)
+        if args.verbose:
+            import traceback
+            traceback.print_exc()
+        return 1
+
+
+def _validate_input_path(models_path: str) -> bool:
+    """Validate that the models path exists and is accessible."""
+    path = Path(models_path)
+
+    if not path.exists():
+        return False
+
+    if not path.is_file() and not path.is_dir():
+        return False
+
+    # Check if it's readable
+    try:
+        with open(path) as f:
+            f.read(1)  # Try to read one character
+        return True
+    except (PermissionError, UnicodeDecodeError):
+        return False
+
+
+def _prepare_output_path(output_path: str, force: bool, backup: bool) -> bool:
+    """Prepare the output path, creating directories and handling existing files."""
+    path = Path(output_path)
+
+    # Create parent directories if they don't exist
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+    except PermissionError:
+        return False
+
+    # Handle existing file
+    if path.exists():
+        if not force:
+            print(f"Output file already exists: {output_path}", file=sys.stderr)
+            print("Use --force to overwrite or --backup to create a backup", file=sys.stderr)
+            return False
+
+        if backup:
+            backup_path = path.with_suffix(f"{path.suffix}.backup.{int(time.time())}")
+            try:
+                path.rename(backup_path)
+                print(f"Created backup: {backup_path}")
+            except PermissionError:
+                print(f"Warning: Could not create backup of {output_path}", file=sys.stderr)
+
+    # Check if we can write to the output location
+    try:
+        path.touch()
+        path.unlink()  # Remove the test file
+        return True
+    except PermissionError:
+        return False
+
+
+def _validate_models(generator: ERDGenerator, verbose: bool) -> bool:
+    """Enhanced model validation with detailed reporting."""
+    try:
+        is_valid = generator.validate_models()
+
+        if not is_valid:
+            if verbose:
+                print("Model validation issues found:")
+                # This could be enhanced to show specific validation errors
+                print("- Check that all models have primary keys")
+                print("- Verify field definitions are correct")
+                print("- Ensure foreign key references are valid")
+
+        return is_valid
+    except Exception as e:
+        if verbose:
+            print(f"Validation error: {e}")
+        return False
+
+
+def _print_output_summary(output_path: str) -> None:
+    """Print summary information about the generated output."""
+    path = Path(output_path)
+
+    if path.exists():
+        file_size = path.stat().st_size
+        print(f"Output file: {output_path}")
+        print(f"File size: {file_size} bytes")
+
+        # Try to count lines
+        try:
+            with open(path) as f:
+                line_count = sum(1 for _ in f)
+            print(f"Line count: {line_count}")
+        except Exception:
+            pass
+
+
+if __name__ == "__main__":
+    sys.exit(main())
diff --git a/backend/tests/contract/test_cli_interface.py b/backend/tests/contract/test_cli_interface.py
new file mode 100644
index 0000000000..967cd83ef7
--- /dev/null
+++ b/backend/tests/contract/test_cli_interface.py
@@ -0,0 +1,165 @@
+"""
+Contract tests for CLI interface based on cli-interface.md contract.
+These tests MUST fail initially and will pass once CLI implementation is complete.
+"""
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+class TestCLIInterface:
+    """Test CLI interface contract compliance."""
+
+    def test_generate_erd_command_exists(self):
+        """Test that generate-erd command is available."""
+        # This should fail until CLI is implemented
+        result = subprocess.run(
+            [sys.executable, "scripts/generate_erd.py", "--help"],
+            capture_output=True,
+            text=True,
+        )
+
+        # Should return help text, not error
+        assert result.returncode == 0
+        assert "Generate Mermaid ERD diagrams" in result.stdout
+        assert "--models-path" in result.stdout
+        assert "--output-path" in result.stdout
+        assert "--validate" in result.stdout
+        assert "--verbose" in result.stdout
+
+    def test_generate_erd_default_behavior(self):
+        """Test default ERD generation without options."""
+        result = subprocess.run(
+            [sys.executable, "scripts/generate_erd.py"],
+            capture_output=True,
+            text=True,
+        )
+
+        # Should succeed with default paths
+        assert result.returncode == 0
+        assert "ERD generation CLI not yet implemented" not in result.stdout
+
+    def test_generate_erd_custom_paths(self):
+        """Test ERD generation with custom model and output paths."""
+        result = subprocess.run(
+            [
+                sys.executable,
+                "scripts/generate_erd.py",
+                "--models-path",
+                "app/models.py",
+                "--output-path",
+                "../docs/database/erd.mmd",
+            ],
+            capture_output=True,
+            text=True,
+        )
+
+        assert result.returncode == 0
+
+    def test_generate_erd_validate_flag(self):
+        """Test ERD generation with validation flag."""
+        result = subprocess.run(
+            [sys.executable, "scripts/generate_erd.py", "--validate"],
+            capture_output=True,
+            text=True,
+        )
+
+        assert result.returncode == 0
+
+    def test_generate_erd_verbose_flag(self):
+        """Test ERD generation with verbose flag."""
+        result = subprocess.run(
+            [sys.executable, "scripts/generate_erd.py", "--verbose"],
+            capture_output=True,
+            text=True,
+        )
+
+        assert result.returncode == 0
+
+    def test_cli_exit_codes(self):
+        """Test CLI exit codes according to contract."""
+        # Test successful generation
+        result = subprocess.run(
+            [sys.executable, "scripts/generate_erd.py"],
+            capture_output=True,
+            text=True,
+        )
+        assert result.returncode == 0
+
+        # Test invalid models file (should return exit code 2)
+        result = subprocess.run(
+            [
+                sys.executable,
+                "scripts/generate_erd.py",
+                "--models-path",
+                "nonexistent.py",
+            ],
+            capture_output=True,
+            text=True,
+        )
+        assert result.returncode == 2
+
+        # Test unwritable output path (should return exit code 3)
+        result = subprocess.run(
+            [
+                sys.executable,
+                "scripts/generate_erd.py",
+                "--output-path",
+                "/nonexistent/path/erd.mmd",
+            ],
+            capture_output=True,
+            text=True,
+        )
+        assert result.returncode == 3
+
+    def test_validate_erd_command(self):
+        """Test validate-erd command functionality."""
+        result = subprocess.run(
+            [sys.executable, "scripts/generate_erd.py", "--validate"],
+            capture_output=True,
+            text=True,
+        )
+
+        assert result.returncode == 0
+        # Should produce validation report
+        assert "validation" in result.stdout.lower() or result.returncode != 0
+
+    def test_error_messages_to_stderr(self):
+        """Test that error messages are written to stderr."""
+        result = subprocess.run(
+            [
+                sys.executable,
+                "scripts/generate_erd.py",
+                "--models-path",
+                "invalid_file.py",
+            ],
+            capture_output=True,
+            text=True,
+        )
+
+        # Error messages should go to stderr
+        if result.returncode != 0:
+            assert result.stderr  # Should have error message
+            assert "invalid_file.py" in result.stderr or result.returncode == 2
+
+    def test_output_file_creation(self):
+        """Test that ERD output file is created."""
+        output_file = Path("../docs/database/erd.mmd")
+
+        # Clean up any existing file
+        if output_file.exists():
+            output_file.unlink()
+
+        result = subprocess.run(
+            [sys.executable, "scripts/generate_erd.py"],
+            capture_output=True,
+            text=True,
+        )
+
+        assert result.returncode == 0
+        assert output_file.exists()
+
+        # File should contain Mermaid ERD syntax
+        content = output_file.read_text()
+        assert "erDiagram" in content or "mermaid" in content.lower()
diff --git a/backend/tests/contract/test_pre_commit_hook.py b/backend/tests/contract/test_pre_commit_hook.py
new file mode 100644
index 0000000000..b8d242918d
--- /dev/null
+++ b/backend/tests/contract/test_pre_commit_hook.py
@@ -0,0 +1,187 @@
+"""
+Contract tests for pre-commit hook integration based on pre-commit-hook.md contract.
+These tests MUST fail initially and will pass once pre-commit hook is implemented.
+"""
+
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+
+class TestPreCommitHook:
+    """Test pre-commit hook contract compliance."""
+
+    def test_pre_commit_config_exists(self):
+        """Test that pre-commit configuration includes ERD generation hook."""
+        config_file = Path(".pre-commit-config.yaml")
+        assert config_file.exists()
+
+        content = config_file.read_text()
+        assert "erd-generation" in content or "generate_erd" in content
+
+    def test_pre_commit_hook_registration(self):
+        """Test that ERD generation hook is properly registered."""
+        result = subprocess.run(
+            [
+                "pre-commit",
+                "run",
+                "--all-files",
+                "--hook-stage",
+                "manual",
+                "erd-generation",
+            ],
+            capture_output=True,
+            text=True,
+        )
+
+        # Hook should exist (may fail until implemented, but should be registered)
+        # If hook doesn't exist, pre-commit should return non-zero
+        # If hook exists but fails, that's expected until implementation
+        assert result.returncode in [0, 1]  # 0 if passes, 1 if hook fails (expected)
+
+    def test_hook_triggers_on_model_changes(self):
+        """Test that hook triggers when SQLModel files are modified."""
+        # Create a temporary test file that looks like a model file
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+            f.write(
+                """
+from sqlmodel import SQLModel, Field
+
+class TestModel(SQLModel, table=True):
+    id: int = Field(primary_key=True)
+    name: str
+"""
+            )
+            temp_file = f.name
+
+        try:
+            # Test that hook would trigger on this file
+            result = subprocess.run(
+                ["pre-commit", "run", "--files", temp_file, "erd-generation"],
+                capture_output=True,
+                text=True,
+            )
+
+            # Hook should attempt to run (may fail until implemented)
+            assert result.returncode in [0, 1]
+        finally:
+            os.unlink(temp_file)
+
+    def test_hook_file_detection(self):
+        """Test that hook detects SQLModel definition files."""
+        # Test with actual models.py file
+        models_file = Path("app/models.py")
+        if models_file.exists():
+            result = subprocess.run(
+                ["pre-commit", "run", "--files", str(models_file), "erd-generation"],
+                capture_output=True,
+                text=True,
+            )
+
+            # Should attempt to run on models file
+            assert result.returncode in [0, 1]
+
+    def test_hook_generates_erd_output(self):
+        """Test that hook generates ERD output when triggered."""
+        # This test will fail until hook is implemented
+        # but should verify the expected behavior
+        result = subprocess.run(
+            ["pre-commit", "run", "--all-files", "erd-generation"],
+            capture_output=True,
+            text=True,
+        )
+
+        # After implementation, should succeed
+        # For now, expect failure until implemented
+        assert result.returncode in [0, 1]
+
+        # If successful, ERD file should exist
+        if result.returncode == 0:
+            erd_file = Path("../docs/database/erd.mmd")
+            assert erd_file.exists()
+
+    def test_hook_validation_integration(self):
+        """Test that hook integrates with validation system."""
+        result = subprocess.run(
+            ["pre-commit", "run", "--all-files", "erd-generation"],
+            capture_output=True,
+            text=True,
+        )
+
+        # Should attempt validation as part of hook process
+        assert result.returncode in [0, 1]
+
+        # Validation output should be present in stdout/stderr
+        output = result.stdout + result.stderr
+        if result.returncode == 1:
+            # If failing, should have validation-related output
+            assert any(
+                word in output.lower() for word in ["validation", "error", "fail"]
+            )
+
+    def test_hook_performance_requirements(self):
+        """Test that hook completes within performance requirements."""
+        import time
+
+        start_time = time.time()
+        result = subprocess.run(
+            ["pre-commit", "run", "--all-files", "erd-generation"],
+            capture_output=True,
+            text=True,
+        )
+        end_time = time.time()
+
+        # Should complete within 30 seconds (performance requirement)
+        duration = end_time - start_time
+        assert duration < 30.0
+
+        # Hook should run (may fail until implemented)
+        assert result.returncode in [0, 1]
+
+    def test_hook_error_handling(self):
+        """Test that hook handles errors gracefully."""
+        # Test with invalid model file
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+            f.write("invalid python syntax !@#$%")
+            temp_file = f.name
+
+        try:
+            result = subprocess.run(
+                ["pre-commit", "run", "--files", temp_file, "erd-generation"],
+                capture_output=True,
+                text=True,
+            )
+
+            # Should fail gracefully with clear error message
+            assert result.returncode == 1
+            assert result.stderr  # Should have error output
+
+        finally:
+            os.unlink(temp_file)
+
+    def test_hook_stages_updated_files(self):
+        """Test that hook stages updated documentation files."""
+        # This test verifies the expected behavior after implementation
+        # For now, just ensure hook runs
+        result = subprocess.run(
+            ["pre-commit", "run", "--all-files", "erd-generation"],
+            capture_output=True,
+            text=True,
+        )
+
+        # Hook should run (may fail until implemented)
+        assert result.returncode in [0, 1]
+
+        # After implementation, should stage updated files
+        # This is verified by checking git status after successful run
+        if result.returncode == 0:
+            git_result = subprocess.run(
+                ["git", "status", "--porcelain"], capture_output=True, text=True
+            )
+
+            # Should show staged changes to ERD documentation
+            assert (
+                "../docs/database/erd.mmd" in git_result.stdout
+                or git_result.returncode != 0
+            )
diff --git a/backend/tests/contract/test_validation_contract.py b/backend/tests/contract/test_validation_contract.py
new file mode 100644
index 0000000000..9cbea68ef7
--- /dev/null
+++ b/backend/tests/contract/test_validation_contract.py
@@ -0,0 +1,256 @@
+"""
+Contract tests for ERD validation system based on validation-contract.md contract.
+These tests MUST fail initially and will pass once validation system is implemented.
+"""
+
+import pytest
+
+
+class TestValidationContract:
+    """Test ERD validation system contract compliance."""
+
+    def test_validation_system_exists(self):
+        """Test that validation system module exists and is importable."""
+        # This should fail until validation system is implemented
+        try:
+            import erd.validation  # noqa: F401  # Test import
+
+            assert True  # Module exists
+        except ImportError:
+            pytest.fail("ERD validation module not found")
+
+    def test_entity_completeness_validation(self):
+        """Test validation of entity completeness and accuracy."""
+        from erd import ERDValidator
+
+        validator = ERDValidator()
+
+        # Test with valid ERD
+        valid_erd = """
+        erDiagram
+            USER {
+                uuid id PK
+                string email
+            }
+        """
+
+        result = validator.validate_entities(valid_erd)
+        assert result.is_valid is True
+        assert len(result.errors) == 0
+
+    def test_field_validation(self):
+        """Test validation of field definitions and types."""
+        from erd import ERDValidator
+
+        validator = ERDValidator()
+
+        # Test field validation
+        test_data = {
+            "entities": [{"name": "User", "fields": [{"name": "id", "type": "uuid"}]}],
+            "models": [{"name": "User", "fields": [{"name": "id", "type": "uuid"}]}],
+        }
+
+        result = validator.validate_fields(test_data)
+        assert result.is_valid is True
+
+    def test_relationship_validation(self):
+        """Test validation of relationship cardinality and constraints."""
+        from erd import ERDValidator
+
+        validator = ERDValidator()
+
+        # Test relationship validation
+        relationships = [
+            {
+                "from_entity": "User",
+                "to_entity": "Item",
+                "cardinality": "1:N",
+                "foreign_key_field": "owner_id",
+            }
+        ]
+
+        result = validator.validate_relationships(relationships)
+        assert result.is_valid is True
+
+    def test_primary_key_validation(self):
+        """Test validation of primary key definitions."""
+        from erd import ERDValidator
+
+        validator = ERDValidator()
+
+        # Test primary key validation
+        entities = [{"name": "User", "primary_key": "id"}]
+
+        result = validator.validate_primary_keys(entities)
+        assert result.is_valid is True
+
+    def test_foreign_key_validation(self):
+        """Test validation of foreign key relationships."""
+        from erd import ERDValidator
+
+        validator = ERDValidator()
+
+        # Test foreign key validation
+        foreign_keys = [
+            {"field": "owner_id", "references": "user.id", "entity": "Item"}
+        ]
+
+        result = validator.validate_foreign_keys(foreign_keys)
+        assert result.is_valid is True
+
+    def test_mermaid_syntax_validation(self):
+        """Test validation of Mermaid ERD syntax."""
+        from erd import ERDValidator
+
+        validator = ERDValidator()
+
+        # Test valid Mermaid syntax
+        valid_mermaid = """
+        erDiagram
+            USER {
+                uuid id PK
+                string email
+            }
+        """
+
+        result = validator.validate_mermaid_syntax(valid_mermaid)
+        assert result.is_valid is True
+
+        # Test invalid Mermaid syntax
+        invalid_mermaid = "invalid syntax !@#$%"
+
+        result = validator.validate_mermaid_syntax(invalid_mermaid)
+        assert result.is_valid is False
+        assert len(result.errors) > 0
+
+    def test_error_severity_levels(self):
+        """Test that validation errors have appropriate severity levels."""
+        from erd import (
+            ERDValidator,
+            ErrorSeverity,
+        )
+
+        validator = ERDValidator()
+
+        # Test critical error (missing entities)
+        result = validator.validate_entities("")
+        assert not result.is_valid
+        assert any(error.severity == ErrorSeverity.CRITICAL for error in result.errors)
+
+        # Test warning error (type mismatches)
+        # This would be implemented with actual type checking
+        assert ErrorSeverity.WARNING in [
+            ErrorSeverity.CRITICAL,
+            ErrorSeverity.WARNING,
+            ErrorSeverity.INFO,
+        ]
+
+    def test_validation_modes(self):
+        """Test different validation modes (strict, permissive, report)."""
+        from erd import ERDValidator, ValidationMode
+
+        validator = ERDValidator()
+
+        # Test strict mode
+        validator.set_mode(ValidationMode.STRICT)
+        assert validator.mode == ValidationMode.STRICT
+
+        # Test permissive mode
+        validator.set_mode(ValidationMode.PERMISSIVE)
+        assert validator.mode == ValidationMode.PERMISSIVE
+
+        # Test report mode
+        validator.set_mode(ValidationMode.REPORT)
+        assert validator.mode == ValidationMode.REPORT
+
+    def test_performance_requirements(self):
+        """Test that validation completes within performance requirements."""
+        import time
+
+        from erd import ERDValidator
+
+        validator = ERDValidator()
+
+        # Test with typical schema
+        test_erd = """
+        erDiagram
+            USER {
+                uuid id PK
+                string email
+                string name
+            }
+            ITEM {
+                uuid id PK
+                string title
+                uuid owner_id FK
+            }
+            USER ||--o{ ITEM : owns
+        """
+
+        start_time = time.time()
+        result = validator.validate_all(test_erd)
+        end_time = time.time()
+
+        # Should complete within 10 seconds
+        duration = end_time - start_time
+        assert duration < 10.0
+        assert result is not None
+
+    def test_validation_configuration(self):
+        """Test validation configuration options."""
+        from erd import ERDValidator, ValidationConfig
+
+        config = ValidationConfig(
+            strict_mode=True,
+            check_syntax=True,
+            validate_relationships=True,
+            validate_constraints=True,
+            max_errors=10,
+            timeout_seconds=30,
+        )
+
+        validator = ERDValidator(config)
+        assert validator.config.strict_mode is True
+        assert validator.config.check_syntax is True
+        assert validator.config.max_errors == 10
+        assert validator.config.timeout_seconds == 30
+
+    def test_validation_integration_points(self):
+        """Test integration with CLI, pre-commit hook, and CI/CD."""
+        from erd import ERDValidator
+
+        validator = ERDValidator()
+
+        # Test CLI integration
+        result = validator.validate_for_cli("test_erd")
+        assert hasattr(result, "is_valid")
+        assert hasattr(result, "errors")
+
+        # Test pre-commit hook integration
+        result = validator.validate_for_pre_commit("test_erd")
+        assert hasattr(result, "is_valid")
+
+        # Test CI/CD integration
+        result = validator.validate_for_ci_cd("test_erd")
+        assert hasattr(result, "is_valid")
+
+    def test_validation_failure_handling(self):
+        """Test handling of validation failures with detailed error messages."""
+        from erd import ERDValidator
+
+        validator = ERDValidator()
+
+        # Test with invalid ERD
+        invalid_erd = "invalid content"
+
+        result = validator.validate_all(invalid_erd)
+        assert not result.is_valid
+        assert len(result.errors) > 0
+
+        # Check error message quality
+        for error in result.errors:
+            assert error.message  # Should have error message
+            assert len(error.message) > 10  # Should be descriptive
+            assert (
+                error.line_number is not None or error.line_number == -1
+            )  # Should have line reference
diff --git a/backend/tests/integration/test_auto_update.py b/backend/tests/integration/test_auto_update.py
new file mode 100644
index 0000000000..6140020c95
--- /dev/null
+++ b/backend/tests/integration/test_auto_update.py
@@ -0,0 +1,265 @@
+"""
+Integration tests for automatic ERD update workflow.
+These tests MUST fail initially and will pass once automatic update is implemented.
+"""
+
+import os
+import subprocess
+import tempfile
+from pathlib import Path
+
+import pytest
+
+
+class TestAutomaticUpdateWorkflow:
+    """Test automatic ERD update workflow integration."""
+
+    def test_pre_commit_hook_auto_update(self):
+        """Test that pre-commit hook automatically updates ERD on model changes."""
+        # Create temporary model file
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+            f.write(
+                """
+from sqlmodel import SQLModel, Field
+import uuid
+
+class TestModel(SQLModel, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    name: str = Field(max_length=255)
+"""
+            )
+            temp_model_file = f.name
+
+        try:
+            # Test pre-commit hook on the temporary file
+            result = subprocess.run(
+                ["pre-commit", "run", "--files", temp_model_file, "erd-generation"],
+                capture_output=True,
+                text=True,
+            )
+
+            # Hook should run (may fail until implemented)
+            assert result.returncode in [0, 1]
+
+            # If successful, should update ERD documentation
+            if result.returncode == 0:
+                erd_file = Path("../docs/database/erd.mmd")
+                assert erd_file.exists()
+
+                # ERD should include the test model
+                erd_content = erd_file.read_text()
+                assert "TestModel" in erd_content or "testmodel" in erd_content.lower()
+
+        finally:
+            os.unlink(temp_model_file)
+
+    def test_git_workflow_integration(self):
+        """Test integration with git workflow for automatic updates."""
+        # Test that git can stage changes to ERD file
+        erd_file = Path("../docs/database/erd.mmd")
+
+        # Ensure ERD file exists
+        if not erd_file.exists():
+            erd_file.parent.mkdir(parents=True, exist_ok=True)
+            erd_file.write_text("# ERD\n```mermaid\nerDiagram\n```")
+
+        # Test git staging of ERD updates
+        result = subprocess.run(
+            ["git", "add", str(erd_file)], capture_output=True, text=True
+        )
+
+        # Should be able to stage ERD file
+        assert result.returncode == 0
+
+        # Check git status shows staged changes
+        status_result = subprocess.run(
+            ["git", "status", "--porcelain"], capture_output=True, text=True
+        )
+
+        # Should show ERD file in staging area
+        assert str(erd_file) in status_result.stdout or status_result.returncode != 0
+
+    def test_model_change_detection(self):
+        """Test detection of model changes triggering ERD updates."""
+        from erd import ModelDiscovery
+
+        discovery = ModelDiscovery()
+
+        # Discover current models
+        _ = discovery.discover_all_models()
+
+        # Create a new model file to simulate changes
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+            f.write(
+                """
+from sqlmodel import SQLModel, Field
+import uuid
+
+class NewModel(SQLModel, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    description: str
+"""
+            )
+            new_model_file = f.name
+
+        try:
+            # Test that discovery detects the new model file
+            new_models = discovery.discover_model_files(new_model_file)
+            assert len(new_models) > 0
+
+            # Extract models from new file
+            extracted_models = discovery.extract_model_classes(Path(new_model_file))
+            assert len(extracted_models) > 0
+            assert extracted_models[0]["name"] == "NewModel"
+
+        finally:
+            os.unlink(new_model_file)
+
+    def test_erd_file_update_integration(self):
+        """Test that ERD file is properly updated with new model information."""
+
+        from erd import ERDGenerator
+
+        generator = ERDGenerator()
+        erd_file = Path("../docs/database/erd.mmd")
+
+        # Record initial file timestamp
+        initial_mtime = erd_file.stat().st_mtime if erd_file.exists() else 0
+
+        # Generate ERD (should update file)
+        generator.generate_erd()
+
+        # File should be updated
+        assert erd_file.exists()
+
+        # File modification time should be newer
+        new_mtime = erd_file.stat().st_mtime
+        assert new_mtime >= initial_mtime
+
+        # File content should contain generated ERD
+        file_content = erd_file.read_text()
+        assert "erDiagram" in file_content or "mermaid" in file_content.lower()
+
+    def test_concurrent_update_prevention(self):
+        """Test that concurrent updates are handled properly."""
+        import threading
+
+        from erd import ERDGenerator
+
+        generator = ERDGenerator()
+        results = []
+
+        def generate_erd():
+            try:
+                result = generator.generate_erd()
+                results.append(("success", result))
+            except Exception as e:
+                results.append(("error", str(e)))
+
+        # Start multiple threads to test concurrent access
+        threads = []
+        for _ in range(3):
+            thread = threading.Thread(target=generate_erd)
+            threads.append(thread)
+            thread.start()
+
+        # Wait for all threads to complete
+        for thread in threads:
+            thread.join(timeout=10)  # 10 second timeout
+
+        # At least one should succeed
+        success_count = sum(1 for result_type, _ in results if result_type == "success")
+        assert success_count >= 1
+
+    def test_rollback_on_failure(self):
+        """Test that failed updates don't leave system in inconsistent state."""
+        from erd import ERDGenerator
+
+        # Create a generator with invalid configuration
+        invalid_generator = ERDGenerator(
+            models_path="nonexistent_models.py", output_path="docs/database/erd.mmd"
+        )
+
+        # Attempt generation should fail gracefully
+        with pytest.raises((FileNotFoundError, PermissionError, OSError)):
+            invalid_generator.generate_erd()
+
+        # ERD file should not be corrupted
+        erd_file = Path("../docs/database/erd.mmd")
+        if erd_file.exists():
+            # File should still be readable
+            content = erd_file.read_text()
+            assert len(content) > 0
+
+    def test_performance_auto_update(self):
+        """Test that automatic updates meet performance requirements."""
+        import time
+
+        start_time = time.time()
+
+        # Simulate pre-commit hook execution
+        result = subprocess.run(
+            ["pre-commit", "run", "--all-files", "erd-generation"],
+            capture_output=True,
+            text=True,
+        )
+
+        end_time = time.time()
+        duration = end_time - start_time
+
+        # Should complete within 30 seconds
+        assert duration < 30.0, f"Auto-update took {duration}s, should be <30s"
+
+        # Hook should run (may fail until implemented)
+        assert result.returncode in [0, 1]
+
+    def test_notification_integration(self):
+        """Test integration with notification system for update status."""
+        from erd import ERDGenerator
+
+        generator = ERDGenerator()
+
+        # Test that generation provides feedback
+        result = generator.generate_erd()
+
+        # Should provide some form of status feedback
+        # This could be return value, logging, or other mechanism
+        assert result is not None  # Should return something
+
+    def test_configuration_update_integration(self):
+        """Test that configuration changes trigger ERD updates."""
+        from erd import ERDGenerator
+
+        # Test with different configurations
+        configs = [
+            {"models_path": "app/models.py"},
+            {"output_path": "../docs/database/erd.mmd"},
+            {
+                "models_path": "app/models.py",
+                "output_path": "../docs/database/erd.mmd",
+            },
+        ]
+
+        for config in configs:
+            generator = ERDGenerator(**config)
+            result = generator.generate_erd()
+
+            # Should work with different configurations
+            assert isinstance(result, str)
+            assert len(result) > 0
+
+    def test_error_recovery_integration(self):
+        """Test error recovery and retry mechanisms."""
+        from erd import ERDGenerator
+
+        # Test that system recovers from temporary failures
+        generator = ERDGenerator()
+
+        # Should be able to generate ERD successfully
+        result = generator.generate_erd()
+        assert isinstance(result, str)
+
+        # Should be able to generate again after first attempt
+        result2 = generator.generate_erd()
+        assert isinstance(result2, str)
+        assert result == result2  # Should be consistent
diff --git a/backend/tests/integration/test_erd_workflow.py b/backend/tests/integration/test_erd_workflow.py
new file mode 100644
index 0000000000..c85015dcba
--- /dev/null
+++ b/backend/tests/integration/test_erd_workflow.py
@@ -0,0 +1,205 @@
+"""
+Integration tests for ERD generation workflow.
+These tests MUST fail initially and will pass once ERD generation is implemented.
+"""
+
+import os
+import tempfile
+from pathlib import Path
+
+import pytest
+
+
+class TestERDGenerationWorkflow:
+    """Test complete ERD generation workflow integration."""
+
+    def test_end_to_end_erd_generation(self):
+        """Test complete end-to-end ERD generation from models to documentation."""
+        from erd import ERDGenerator
+
+        generator = ERDGenerator()
+
+        # Test with existing models.py
+        models_path = Path("app/models.py")
+        assert models_path.exists(), "models.py file should exist"
+
+        # Generate ERD
+        result = generator.generate_erd()
+        assert isinstance(result, str)
+        assert len(result) > 0
+
+        # Should contain Mermaid ERD syntax
+        assert "erDiagram" in result
+
+        # Should contain entities from models.py
+        assert "USER" in result.upper() or "User" in result
+        assert "ITEM" in result.upper() or "Item" in result
+
+    def test_model_discovery_integration(self):
+        """Test integration between ERD generator and model discovery."""
+        from erd import ERDGenerator
+        from erd import ModelDiscovery
+
+        # Test model discovery
+        discovery = ModelDiscovery()
+        model_files = discovery.discover_model_files()
+        assert len(model_files) > 0
+
+        # Test ERD generation with discovered models
+        generator = ERDGenerator()
+        result = generator.generate_erd()
+
+        # Should generate ERD based on discovered models
+        assert isinstance(result, str)
+        assert "erDiagram" in result
+
+    def test_file_output_integration(self):
+        """Test that ERD generation writes to correct output file."""
+        from erd import ERDGenerator
+
+        # Use temporary file for testing
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".md", delete=False) as f:
+            temp_output = f.name
+
+        try:
+            generator = ERDGenerator(output_path=temp_output)
+            result = generator.generate_erd()
+
+            # Should write to file
+            assert Path(temp_output).exists()
+
+            # File content should match generated ERD
+            file_content = Path(temp_output).read_text()
+            assert file_content == result
+            assert "erDiagram" in file_content
+
+        finally:
+            if os.path.exists(temp_output):
+                os.unlink(temp_output)
+
+    def test_sqlmodel_parsing_integration(self):
+        """Test integration with SQLModel parsing and AST analysis."""
+        from erd import ERDGenerator
+        from erd import ModelDiscovery
+
+        # Test parsing of actual SQLModel definitions
+        discovery = ModelDiscovery()
+        models = discovery.discover_all_models()
+
+        assert len(models) > 0, "Should discover models from models.py"
+
+        # Test ERD generation incorporates parsed model information
+        generator = ERDGenerator()
+        result = generator.generate_erd()
+
+        # Should include model information in ERD
+        assert "erDiagram" in result
+
+        # Should include fields and relationships from parsed models
+        for _file_path, model_list in models.items():
+            for model in model_list:
+                assert model["name"].upper() in result or model["name"] in result
+
+    def test_relationship_mapping_integration(self):
+        """Test integration of relationship mapping in ERD generation."""
+        from erd import ERDGenerator
+
+        generator = ERDGenerator()
+        result = generator.generate_erd()
+
+        # Should include relationships between entities
+        assert "erDiagram" in result
+
+        # Should show foreign key relationships
+        # Based on models.py, should have User-Item relationship
+        if "USER" in result.upper() and "ITEM" in result.upper():
+            # Should show relationship between User and Item
+            assert "||--o{" in result or "--" in result
+
+    def test_constraint_representation_integration(self):
+        """Test integration of constraint representation in ERD."""
+        from erd import ERDGenerator
+
+        generator = ERDGenerator()
+        result = generator.generate_erd()
+
+        # Should represent constraints (PK, FK, etc.)
+        assert "erDiagram" in result
+
+        # Should show primary keys
+        assert "PK" in result or "primary" in result.lower()
+
+        # Should show foreign keys
+        assert "FK" in result or "foreign" in result.lower()
+
+    def test_error_handling_integration(self):
+        """Test integration of error handling throughout workflow."""
+        from erd import ERDGenerator
+
+        generator = ERDGenerator()
+
+        # Test with invalid models path
+        invalid_generator = ERDGenerator(models_path="nonexistent.py")
+
+        with pytest.raises((FileNotFoundError, PermissionError, OSError)):
+            invalid_generator.generate_erd()
+
+        # Test with valid path should work
+        result = generator.generate_erd()
+        assert isinstance(result, str)
+
+    def test_performance_integration(self):
+        """Test that complete workflow meets performance requirements."""
+        import time
+
+        from erd import ERDGenerator
+
+        generator = ERDGenerator()
+
+        # Test performance requirement: <30 seconds for typical schemas
+        start_time = time.time()
+        result = generator.generate_erd()
+        end_time = time.time()
+
+        duration = end_time - start_time
+        assert duration < 30.0, f"ERD generation took {duration}s, should be <30s"
+
+        # Should still produce valid result
+        assert isinstance(result, str)
+        assert len(result) > 0
+
+    def test_validation_integration(self):
+        """Test integration with validation system."""
+        from erd import ERDGenerator
+        from erd import ERDValidator
+
+        generator = ERDGenerator()
+        validator = ERDValidator()
+
+        # Generate ERD
+        erd_result = generator.generate_erd()
+
+        # Validate generated ERD
+        validation_result = validator.validate_all(erd_result)
+
+        # Should pass validation
+        assert validation_result.is_valid is True
+        assert len(validation_result.errors) == 0
+
+    def test_documentation_format_integration(self):
+        """Test that generated ERD is properly formatted for documentation."""
+        from erd import ERDGenerator
+
+        generator = ERDGenerator()
+        result = generator.generate_erd()
+
+        # Should be properly formatted for Markdown
+        assert "```mermaid" in result or "erDiagram" in result
+
+        # Should have proper structure
+        lines = result.split("\n")
+        assert any("erDiagram" in line for line in lines)
+
+        # Should be readable and well-formatted
+        assert len(result.strip()) > 0
+        assert not result.startswith(" ")  # Should not have leading whitespace issues
diff --git a/backend/tests/integration/test_error_handling.py b/backend/tests/integration/test_error_handling.py
new file mode 100644
index 0000000000..673f99ae89
--- /dev/null
+++ b/backend/tests/integration/test_error_handling.py
@@ -0,0 +1,348 @@
+"""
+Integration tests for error handling workflow.
+These tests MUST fail initially and will pass once error handling is implemented.
+"""
+
+import os
+import tempfile
+from unittest.mock import patch
+
+import pytest
+
+
+class TestErrorHandlingWorkflow:
+    """Test error handling workflow integration."""
+
+    def test_invalid_sqlmodel_syntax_handling(self):
+        """Test handling of invalid SQLModel syntax."""
+        from erd import ERDGenerator
+
+        # Create temporary file with invalid SQLModel syntax
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+            f.write(
+                """
+from sqlmodel import SQLModel, Field
+
+class InvalidModel(SQLModel, table=True):
+    # Missing field definition
+    invalid_syntax !@#$%
+    id: int = Field(primary_key=True)
+"""
+            )
+            invalid_model_file = f.name
+
+        try:
+            # Test ERD generation with invalid model
+            generator = ERDGenerator(models_path=invalid_model_file)
+
+            # Should fail fast with clear error message
+            with pytest.raises(Exception) as exc_info:
+                generator.generate_erd()
+
+            # Error message should be clear and helpful
+            error_msg = str(exc_info.value)
+            assert len(error_msg) > 10  # Should be descriptive
+            assert "syntax" in error_msg.lower() or "invalid" in error_msg.lower()
+
+        finally:
+            os.unlink(invalid_model_file)
+
+    def test_malformed_model_definition_handling(self):
+        """Test handling of malformed model definitions."""
+        from erd import ERDGenerator
+
+        # Create temporary file with malformed model
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+            f.write(
+                """
+from sqlmodel import SQLModel, Field
+
+# Missing table=True
+class MalformedModel(SQLModel):
+    id: int = Field(primary_key=True)
+    name: str
+
+# Invalid field definition
+class AnotherBadModel(SQLModel, table=True):
+    # Invalid field syntax
+    name: = Field(max_length=255)
+"""
+            )
+            malformed_file = f.name
+
+        try:
+            generator = ERDGenerator(models_path=malformed_file)
+
+            # Should handle malformed models gracefully
+            with pytest.raises(Exception) as exc_info:
+                generator.generate_erd()
+
+            # Should provide specific error information
+            error_msg = str(exc_info.value)
+            assert "malformed" in error_msg.lower() or "invalid" in error_msg.lower()
+
+        finally:
+            os.unlink(malformed_file)
+
+    def test_circular_relationship_handling(self):
+        """Test handling of circular relationships between entities."""
+        from erd import ERDGenerator
+
+        # Create temporary file with circular relationships
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+            f.write(
+                """
+from sqlmodel import SQLModel, Field, Relationship
+import uuid
+
+class Parent(SQLModel, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    name: str
+    child_id: uuid.UUID = Field(foreign_key="child.id")
+    child: "Child" = Relationship(back_populates="parent")
+
+class Child(SQLModel, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    name: str
+    parent_id: uuid.UUID = Field(foreign_key="parent.id")
+    parent: Parent = Relationship(back_populates="child")
+"""
+            )
+            circular_file = f.name
+
+        try:
+            generator = ERDGenerator(models_path=circular_file)
+
+            # Should handle circular relationships
+            result = generator.generate_erd()
+
+            # Should generate ERD despite circular relationships
+            assert isinstance(result, str)
+            assert "erDiagram" in result
+            assert "Parent" in result
+            assert "Child" in result
+
+        finally:
+            os.unlink(circular_file)
+
+    def test_missing_dependency_handling(self):
+        """Test handling of missing dependencies or imports."""
+        from erd import ERDGenerator
+
+        # Create temporary file with missing imports
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+            f.write(
+                """
+# Missing import: from sqlmodel import SQLModel, Field
+import uuid
+
+class ModelWithoutImport(SQLModel, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    name: str
+"""
+            )
+            missing_import_file = f.name
+
+        try:
+            generator = ERDGenerator(models_path=missing_import_file)
+
+            # Should handle missing imports gracefully
+            with pytest.raises(Exception) as exc_info:
+                generator.generate_erd()
+
+            # Should provide helpful error message
+            error_msg = str(exc_info.value)
+            assert "import" in error_msg.lower() or "dependency" in error_msg.lower()
+
+        finally:
+            os.unlink(missing_import_file)
+
+    def test_file_permission_error_handling(self):
+        """Test handling of file permission errors."""
+        from erd import ERDGenerator
+
+        # Test with unwritable output path
+        generator = ERDGenerator(output_path="/root/unwritable/erd.mmd")
+
+        # Should handle permission errors gracefully
+        with pytest.raises(Exception) as exc_info:
+            generator.generate_erd()
+
+        # Should provide clear error message
+        error_msg = str(exc_info.value)
+        assert "permission" in error_msg.lower() or "access" in error_msg.lower()
+
+    def test_memory_error_handling(self):
+        """Test handling of memory errors during processing."""
+        from erd import ERDGenerator
+
+        # Create a very large model file to test memory handling
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+            f.write("from sqlmodel import SQLModel, Field\nimport uuid\n\n")
+
+            # Generate many models to test memory limits
+            for i in range(100):  # Reasonable number for testing
+                f.write(
+                    f"""
+class Model{i}(SQLModel, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    name: str = Field(max_length=255)
+    description: str = Field(max_length=1000)
+"""
+                )
+
+            large_file = f.name
+
+        try:
+            generator = ERDGenerator(models_path=large_file)
+
+            # Should handle large models within memory constraints
+            result = generator.generate_erd()
+
+            # Should generate ERD for large schema
+            assert isinstance(result, str)
+            assert "erDiagram" in result
+
+            # Should include some models
+            assert "Model" in result
+
+        finally:
+            os.unlink(large_file)
+
+    def test_timeout_error_handling(self):
+        """Test handling of timeout errors during generation."""
+        import time
+
+        from erd import ERDGenerator
+
+        generator = ERDGenerator()
+
+        # Test that generation completes within timeout
+        start_time = time.time()
+        result = generator.generate_erd()
+        end_time = time.time()
+
+        # Should complete within 30 seconds (performance requirement)
+        duration = end_time - start_time
+        assert duration < 30.0, f"Generation took {duration}s, should be <30s"
+
+        # Should still produce valid result
+        assert isinstance(result, str)
+
+    def test_partial_failure_recovery(self):
+        """Test recovery from partial failures."""
+        from erd import ERDGenerator
+
+        # Create file with mix of valid and invalid models
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".py", delete=False) as f:
+            f.write(
+                """
+from sqlmodel import SQLModel, Field
+import uuid
+
+class ValidModel(SQLModel, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    name: str
+
+# Invalid model
+class InvalidModel(SQLModel, table=True):
+    invalid_syntax !@#$%
+
+class AnotherValidModel(SQLModel, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    title: str
+"""
+            )
+            mixed_file = f.name
+
+        try:
+            generator = ERDGenerator(models_path=mixed_file)
+
+            # Should handle mixed valid/invalid models
+            # Either fail fast or skip invalid models and process valid ones
+            try:
+                result = generator.generate_erd()
+                # If succeeds, should include valid models
+                assert isinstance(result, str)
+                assert "ValidModel" in result or "AnotherValidModel" in result
+            except Exception:
+                # If fails, should fail fast with clear error
+                pass  # Acceptable behavior
+
+        finally:
+            os.unlink(mixed_file)
+
+    def test_error_logging_integration(self):
+        """Test integration with error logging system."""
+        from erd import ERDGenerator
+
+        # Test that errors are properly logged
+        with patch("logging.error") as _mock_logging:
+            try:
+                # Create invalid generator to trigger error
+                invalid_generator = ERDGenerator(models_path="nonexistent.py")
+                invalid_generator.generate_erd()
+            except Exception:
+                pass  # Expected to fail
+
+            # Should log errors appropriately
+            # Note: This test may need adjustment based on actual logging implementation
+
+    def test_user_friendly_error_messages(self):
+        """Test that error messages are user-friendly and actionable."""
+        from erd import ERDGenerator
+
+        # Test various error scenarios
+        error_scenarios = [
+            ("nonexistent.py", "File not found"),
+            ("/unwritable/path/erd.mmd", "Permission denied"),
+            ("invalid_syntax.py", "Syntax error"),
+        ]
+
+        for models_path, expected_error_type in error_scenarios:
+            generator = ERDGenerator(models_path=models_path)
+
+            try:
+                generator.generate_erd()
+            except Exception as exc_info:
+                error_msg = str(exc_info)
+
+                # Error message should be descriptive and helpful
+                assert len(error_msg) > 10
+                assert not any(
+                    char in error_msg for char in ["!", "@", "#", "$", "%"]
+                )  # No gibberish
+
+                # Should contain actionable information
+                actionable_words = [
+                    "check",
+                    "verify",
+                    "ensure",
+                    "try",
+                    "fix",
+                    "correct",
+                ]
+                assert (
+                    any(word in error_msg.lower() for word in actionable_words)
+                    or expected_error_type.lower() in error_msg.lower()
+                )
+
+    def test_error_context_preservation(self):
+        """Test that error context is preserved for debugging."""
+        from erd import ERDGenerator
+
+        # Test that errors include sufficient context
+        try:
+            invalid_generator = ERDGenerator(models_path="nonexistent.py")
+            invalid_generator.generate_erd()
+        except Exception as exc_info:
+            error_msg = str(exc_info)
+
+            # Should include file path in error
+            assert "nonexistent.py" in error_msg
+
+            # Should include operation context
+            assert any(
+                word in error_msg.lower()
+                for word in ["generate", "erd", "model", "parse"]
+            )
diff --git a/backend/tests/performance/test_erd_performance.py b/backend/tests/performance/test_erd_performance.py
new file mode 100644
index 0000000000..18df0d863d
--- /dev/null
+++ b/backend/tests/performance/test_erd_performance.py
@@ -0,0 +1,406 @@
+"""
+Performance tests for ERD generation.
+
+Tests that ERD generation completes within performance requirements:
+- <30 seconds for schemas with up to 20 tables and 100 fields
+- Memory usage stays reasonable for large schemas
+- Generation time scales appropriately with schema size
+"""
+
+import pytest
+import time
+import tempfile
+from pathlib import Path
+from unittest.mock import patch
+
+from erd import ERDGenerator, ModelMetadata, FieldMetadata, RelationshipMetadata
+
+
+class TestERDPerformance:
+    """Test ERD generation performance requirements."""
+
+    def test_performance_small_schema(self):
+        """Test performance with small schema (2 tables, 10 fields)."""
+        generator = ERDGenerator()
+        
+        start_time = time.time()
+        
+        # Mock a small schema
+        with patch.object(generator, '_discover_models') as mock_discover, \
+             patch.object(generator, '_extract_model_metadata') as mock_extract:
+            
+            # Create small schema
+            user_metadata = ModelMetadata(
+                class_name="User",
+                table_name="USER",
+                file_path=Path("test.py"),
+                line_number=1,
+                fields=[
+                    FieldMetadata(name=f"field_{i}", type_hint="str")
+                    for i in range(5)
+                ],
+                relationships=[],
+                constraints=[]
+            )
+            
+            item_metadata = ModelMetadata(
+                class_name="Item",
+                table_name="ITEM",
+                file_path=Path("test.py"),
+                line_number=10,
+                fields=[
+                    FieldMetadata(name=f"field_{i}", type_hint="str")
+                    for i in range(5)
+                ],
+                relationships=[],
+                constraints=[]
+            )
+            
+            generator.generated_models = {
+                "User": user_metadata,
+                "Item": item_metadata
+            }
+            
+            # Generate ERD
+            result = generator.generate_erd()
+            
+            end_time = time.time()
+            generation_time = end_time - start_time
+            
+            # Should complete very quickly (under 1 second for small schema)
+            assert generation_time < 1.0, f"Small schema took {generation_time:.2f} seconds"
+            assert result is not None
+            assert "erDiagram" in result
+
+    def test_performance_medium_schema(self):
+        """Test performance with medium schema (10 tables, 50 fields)."""
+        generator = ERDGenerator()
+        
+        start_time = time.time()
+        
+        # Mock a medium schema
+        with patch.object(generator, '_discover_models') as mock_discover, \
+             patch.object(generator, '_extract_model_metadata') as mock_extract:
+            
+            # Create medium schema with 10 tables
+            generated_models = {}
+            for i in range(10):
+                table_name = f"TABLE_{i:02d}"
+                model_metadata = ModelMetadata(
+                    class_name=f"Model{i}",
+                    table_name=table_name,
+                    file_path=Path("test.py"),
+                    line_number=i * 10,
+                    fields=[
+                        FieldMetadata(
+                            name="id",
+                            type_hint="uuid.UUID",
+                            is_primary_key=True
+                        )
+                    ] + [
+                        FieldMetadata(name=f"field_{j}", type_hint="str")
+                        for j in range(4)  # 5 fields per table = 50 total
+                    ],
+                    relationships=[],
+                    constraints=[]
+                )
+                generated_models[f"Model{i}"] = model_metadata
+            
+            generator.generated_models = generated_models
+            
+            # Generate ERD
+            result = generator.generate_erd()
+            
+            end_time = time.time()
+            generation_time = end_time - start_time
+            
+            # Should complete within reasonable time (under 5 seconds for medium schema)
+            assert generation_time < 5.0, f"Medium schema took {generation_time:.2f} seconds"
+            assert result is not None
+            assert "erDiagram" in result
+            assert len(generated_models) == 10
+
+    def test_performance_large_schema(self):
+        """Test performance with large schema (20 tables, 100 fields)."""
+        generator = ERDGenerator()
+        
+        start_time = time.time()
+        
+        # Mock a large schema
+        with patch.object(generator, '_discover_models') as mock_discover, \
+             patch.object(generator, '_extract_model_metadata') as mock_extract:
+            
+            # Create large schema with 20 tables
+            generated_models = {}
+            for i in range(20):
+                table_name = f"TABLE_{i:02d}"
+                model_metadata = ModelMetadata(
+                    class_name=f"Model{i}",
+                    table_name=table_name,
+                    file_path=Path("test.py"),
+                    line_number=i * 10,
+                    fields=[
+                        FieldMetadata(
+                            name="id",
+                            type_hint="uuid.UUID",
+                            is_primary_key=True
+                        )
+                    ] + [
+                        FieldMetadata(name=f"field_{j}", type_hint="str")
+                        for j in range(4)  # 5 fields per table = 100 total
+                    ],
+                    relationships=[],
+                    constraints=[]
+                )
+                generated_models[f"Model{i}"] = model_metadata
+            
+            generator.generated_models = generated_models
+            
+            # Generate ERD
+            result = generator.generate_erd()
+            
+            end_time = time.time()
+            generation_time = end_time - start_time
+            
+            # Must complete within 30 seconds (requirement)
+            assert generation_time < 30.0, f"Large schema took {generation_time:.2f} seconds (requirement: <30s)"
+            assert result is not None
+            assert "erDiagram" in result
+            assert len(generated_models) == 20
+
+    def test_performance_complex_relationships(self):
+        """Test performance with complex relationship schema."""
+        generator = ERDGenerator()
+        
+        start_time = time.time()
+        
+        # Mock a schema with complex relationships
+        with patch.object(generator, '_discover_models') as mock_discover, \
+             patch.object(generator, '_extract_model_metadata') as mock_extract:
+            
+            # Create schema with many relationships
+            generated_models = {}
+            
+            # Create main user table
+            user_metadata = ModelMetadata(
+                class_name="User",
+                table_name="USER",
+                file_path=Path("test.py"),
+                line_number=1,
+                fields=[
+                    FieldMetadata(name="id", type_hint="uuid.UUID", is_primary_key=True),
+                    FieldMetadata(name="email", type_hint="str"),
+                    FieldMetadata(name="name", type_hint="str")
+                ],
+                relationships=[],
+                constraints=[]
+            )
+            generated_models["User"] = user_metadata
+            
+            # Create 15 related tables with relationships
+            for i in range(15):
+                table_name = f"ITEM_{i:02d}"
+                model_metadata = ModelMetadata(
+                    class_name=f"Item{i}",
+                    table_name=table_name,
+                    file_path=Path("test.py"),
+                    line_number=(i + 1) * 10,
+                    fields=[
+                        FieldMetadata(name="id", type_hint="uuid.UUID", is_primary_key=True),
+                        FieldMetadata(name="title", type_hint="str"),
+                        FieldMetadata(name="user_id", type_hint="uuid.UUID", is_foreign_key=True)
+                    ],
+                    relationships=[
+                        RelationshipMetadata(
+                            field_name="owner",
+                            target_model="User",
+                            relationship_type="many-to-one",
+                            back_populates=f"items_{i}",
+                            foreign_key_field="user_id",
+                            cascade=None
+                        )
+                    ],
+                    constraints=[]
+                )
+                generated_models[f"Item{i}"] = model_metadata
+                
+                # Add relationship to user
+                user_metadata.relationships.append(
+                    RelationshipMetadata(
+                        field_name=f"items_{i}",
+                        target_model=f"Item{i}",
+                        relationship_type="one-to-many",
+                        back_populates="owner",
+                        foreign_key_field=None,
+                        cascade=None
+                    )
+                )
+            
+            generator.generated_models = generated_models
+            
+            # Generate ERD
+            result = generator.generate_erd()
+            
+            end_time = time.time()
+            generation_time = end_time - start_time
+            
+            # Should handle complex relationships efficiently
+            assert generation_time < 10.0, f"Complex relationships took {generation_time:.2f} seconds"
+            assert result is not None
+            assert "erDiagram" in result
+            assert len(generated_models) == 16  # 1 User + 15 Items
+
+    def test_performance_memory_usage(self):
+        """Test memory usage with large schema."""
+        import psutil
+        import os
+        
+        generator = ERDGenerator()
+        process = psutil.Process(os.getpid())
+        
+        # Get initial memory usage
+        initial_memory = process.memory_info().rss / 1024 / 1024  # MB
+        
+        # Mock a large schema
+        with patch.object(generator, '_discover_models') as mock_discover, \
+             patch.object(generator, '_extract_model_metadata') as mock_extract:
+            
+            # Create large schema with 20 tables
+            generated_models = {}
+            for i in range(20):
+                table_name = f"TABLE_{i:02d}"
+                model_metadata = ModelMetadata(
+                    class_name=f"Model{i}",
+                    table_name=table_name,
+                    file_path=Path("test.py"),
+                    line_number=i * 10,
+                    fields=[
+                        FieldMetadata(name="id", type_hint="uuid.UUID", is_primary_key=True)
+                    ] + [
+                        FieldMetadata(name=f"field_{j}", type_hint="str")
+                        for j in range(9)  # 10 fields per table
+                    ],
+                    relationships=[],
+                    constraints=[]
+                )
+                generated_models[f"Model{i}"] = model_metadata
+            
+            generator.generated_models = generated_models
+            
+            # Generate ERD
+            result = generator.generate_erd()
+            
+            # Check memory usage
+            final_memory = process.memory_info().rss / 1024 / 1024  # MB
+            memory_increase = final_memory - initial_memory
+            
+            # Memory increase should be reasonable (under 100MB for large schema)
+            assert memory_increase < 100, f"Memory increased by {memory_increase:.1f}MB"
+            assert result is not None
+
+    def test_performance_scaling_linear(self):
+        """Test that generation time scales approximately linearly with schema size."""
+        generator = ERDGenerator()
+        
+        # Test with different schema sizes
+        schema_sizes = [5, 10, 15, 20]
+        generation_times = []
+        
+        for size in schema_sizes:
+            with patch.object(generator, '_discover_models') as mock_discover, \
+                 patch.object(generator, '_extract_model_metadata') as mock_extract:
+                
+                # Create schema with specified size
+                generated_models = {}
+                for i in range(size):
+                    table_name = f"TABLE_{i:02d}"
+                    model_metadata = ModelMetadata(
+                        class_name=f"Model{i}",
+                        table_name=table_name,
+                        file_path=Path("test.py"),
+                        line_number=i * 10,
+                        fields=[
+                            FieldMetadata(name="id", type_hint="uuid.UUID", is_primary_key=True),
+                            FieldMetadata(name="name", type_hint="str")
+                        ],
+                        relationships=[],
+                        constraints=[]
+                    )
+                    generated_models[f"Model{i}"] = model_metadata
+                
+                generator.generated_models = generated_models
+                
+                start_time = time.time()
+                result = generator.generate_erd()
+                end_time = time.time()
+                
+                generation_time = end_time - start_time
+                generation_times.append(generation_time)
+        
+        # Check that times are reasonable for all sizes
+        for i, time_taken in enumerate(generation_times):
+            assert time_taken < 30.0, f"Schema size {schema_sizes[i]} took {time_taken:.2f} seconds"
+        
+        # Check that scaling is approximately linear (not exponential)
+        # Time should not increase dramatically between sizes
+        for i in range(1, len(generation_times)):
+            ratio = generation_times[i] / generation_times[i-1]
+            assert ratio < 3.0, f"Scaling ratio {ratio:.2f} is too high between sizes {schema_sizes[i-1]} and {schema_sizes[i]}"
+
+    def test_performance_file_operations(self):
+        """Test performance of file operations during ERD generation."""
+        generator = ERDGenerator()
+        
+        # Create temporary file for testing
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.mmd', delete=False) as temp_file:
+            temp_path = temp_file.name
+        
+        try:
+            # Set custom output path
+            generator.output_path = temp_path
+            
+            start_time = time.time()
+            
+            # Mock a medium schema
+            with patch.object(generator, '_discover_models') as mock_discover, \
+                 patch.object(generator, '_extract_model_metadata') as mock_extract:
+                
+                # Create schema with 10 tables
+                generated_models = {}
+                for i in range(10):
+                    table_name = f"TABLE_{i:02d}"
+                    model_metadata = ModelMetadata(
+                        class_name=f"Model{i}",
+                        table_name=table_name,
+                        file_path=Path("test.py"),
+                        line_number=i * 10,
+                        fields=[
+                            FieldMetadata(name="id", type_hint="uuid.UUID", is_primary_key=True),
+                            FieldMetadata(name="name", type_hint="str")
+                        ],
+                        relationships=[],
+                        constraints=[]
+                    )
+                    generated_models[f"Model{i}"] = model_metadata
+                
+                generator.generated_models = generated_models
+                
+                # Generate ERD (includes file operations)
+                result = generator.generate_erd()
+                
+                end_time = time.time()
+                generation_time = end_time - start_time
+            
+            # File operations should not significantly impact performance
+            assert generation_time < 5.0, f"File operations took {generation_time:.2f} seconds"
+            
+            # Verify file was created
+            assert Path(temp_path).exists()
+            
+            # Verify file content
+            file_content = Path(temp_path).read_text()
+            assert "erDiagram" in file_content
+            
+        finally:
+            # Clean up temporary file
+            Path(temp_path).unlink(missing_ok=True)
diff --git a/backend/tests/unit/erd/test_mermaid_validator.py b/backend/tests/unit/erd/test_mermaid_validator.py
new file mode 100644
index 0000000000..8fe622ddbe
--- /dev/null
+++ b/backend/tests/unit/erd/test_mermaid_validator.py
@@ -0,0 +1,211 @@
+"""
+Unit tests for Mermaid ERD syntax validation.
+"""
+
+import pytest
+from pathlib import Path
+
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+from erd import MermaidValidator
+
+
+class TestMermaidValidator:
+    """Test Mermaid syntax validation."""
+
+    def test_valid_erd_syntax(self):
+        """Test validation of valid ERD syntax."""
+        validator = MermaidValidator()
+        
+        valid_erd = """
+erDiagram
+
+USER {
+    uuid id PK
+    string name
+}
+
+ITEM {
+    uuid id PK
+    string title
+    uuid owner_id FK
+}
+
+USER ||--}o ITEM : owns
+"""
+        
+        result = validator.validate_erd_structure(valid_erd)
+        assert result.is_valid
+        assert len(result.errors) == 0
+
+    def test_missing_erdiagram_declaration(self):
+        """Test detection of missing erDiagram declaration."""
+        validator = MermaidValidator()
+        
+        invalid_erd = """
+USER {
+    uuid id PK
+}
+
+ITEM {
+    uuid id PK
+}
+"""
+        
+        result = validator.validate_erd_structure(invalid_erd)
+        assert not result.is_valid
+        assert any("Missing erDiagram declaration" in error.message for error in result.errors)
+
+    def test_no_entities(self):
+        """Test detection of ERD with no entities."""
+        validator = MermaidValidator()
+        
+        invalid_erd = """
+erDiagram
+
+USER ||--}o ITEM : owns
+"""
+        
+        result = validator.validate_erd_structure(invalid_erd)
+        assert not result.is_valid
+        assert any("No entities found" in error.message for error in result.errors)
+
+    def test_invalid_relationship_syntax(self):
+        """Test detection of invalid relationship syntax."""
+        validator = MermaidValidator()
+        
+        invalid_erd = """
+erDiagram
+
+USER {
+    uuid id PK
+}
+
+ITEM {
+    uuid id PK
+}
+
+USER -- ITEM : invalid
+"""
+        
+        result = validator.validate_erd_structure(invalid_erd)
+        assert not result.is_valid
+        assert any("Invalid relationship syntax" in error.message for error in result.errors)
+
+    def test_unmatched_braces(self):
+        """Test detection of unmatched braces."""
+        validator = MermaidValidator()
+        
+        invalid_erd = """
+erDiagram
+
+USER {
+    uuid id PK
+    string name
+"""
+        
+        result = validator.validate_erd_structure(invalid_erd)
+        assert not result.is_valid
+        assert any("Unmatched braces" in error.message for error in result.errors)
+
+    def test_entity_and_relationship_counting(self):
+        """Test accurate counting of entities and relationships."""
+        validator = MermaidValidator()
+        
+        erd = """
+erDiagram
+
+USER {
+    uuid id PK
+    string name
+}
+
+ITEM {
+    uuid id PK
+    string title
+}
+
+CATEGORY {
+    uuid id PK
+    string name
+}
+
+USER ||--}o ITEM : owns
+ITEM }o--|| CATEGORY : belongs_to
+"""
+        
+        result = validator.validate_erd_structure(erd)
+        assert result.is_valid
+        
+        # Check info messages for counts
+        info_messages = [warning.message for warning in result.warnings]
+        assert any("3 entities" in msg for msg in info_messages)
+        assert any("2 relationships" in msg for msg in info_messages)
+
+    def test_mermaid_cli_availability_check(self):
+        """Test Mermaid CLI availability detection."""
+        validator = MermaidValidator()
+        
+        # This test just ensures the method doesn't crash
+        # The actual availability depends on the test environment
+        cli_available = validator.mermaid_cli_available
+        assert isinstance(cli_available, bool)
+
+    def test_complete_validation_workflow(self):
+        """Test complete validation workflow."""
+        validator = MermaidValidator()
+        
+        valid_erd = """
+erDiagram
+
+USER {
+    uuid id PK
+    string name
+}
+
+ITEM {
+    uuid id PK
+    string title
+    uuid owner_id FK
+}
+
+USER ||--}o ITEM : owns
+"""
+        
+        result = validator.validate_complete(valid_erd)
+        
+        # Structure validation should pass
+        assert result.is_valid or len(result.errors) == 0
+        
+        # Should have info about entities and relationships
+        info_messages = [warning.message for warning in result.warnings]
+        assert any("entities" in msg and "relationships" in msg for msg in info_messages)
+
+    def test_validation_with_comments(self):
+        """Test validation with Mermaid comments."""
+        validator = MermaidValidator()
+        
+        erd_with_comments = """
+%% Database ERD Diagram
+%% Generated: 2024-01-01T00:00:00
+
+erDiagram
+
+USER {
+    uuid id PK
+    string name
+}
+
+ITEM {
+    uuid id PK
+    string title
+}
+
+%% User owns many items
+USER ||--}o ITEM : owns
+"""
+        
+        result = validator.validate_erd_structure(erd_with_comments)
+        assert result.is_valid
+        assert len(result.errors) == 0
diff --git a/backend/tests/unit/erd_tests/__init__.py b/backend/tests/unit/erd_tests/__init__.py
new file mode 100644
index 0000000000..254b40628a
--- /dev/null
+++ b/backend/tests/unit/erd_tests/__init__.py
@@ -0,0 +1,6 @@
+"""
+ERD Unit Tests Package.
+
+This package contains unit tests for the ERD (Entity Relationship Diagram) 
+generation functionality.
+"""
diff --git a/backend/tests/unit/erd_tests/test_generator.py b/backend/tests/unit/erd_tests/test_generator.py
new file mode 100644
index 0000000000..b397f5be15
--- /dev/null
+++ b/backend/tests/unit/erd_tests/test_generator.py
@@ -0,0 +1,412 @@
+"""
+Unit tests for ERD Generator module.
+
+Tests the core ERD generation functionality including model discovery,
+metadata extraction, relationship generation, and Mermaid output.
+"""
+
+import pytest
+from pathlib import Path
+from unittest.mock import Mock, patch, MagicMock
+
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+from erd import ERDGenerator, ModelMetadata, FieldMetadata, RelationshipMetadata, ERDOutput, EntityDefinition, RelationshipDefinition
+
+
+class TestERDGenerator:
+    """Test ERD Generator core functionality."""
+
+    def test_initialization(self):
+        """Test ERD Generator initialization with default parameters."""
+        generator = ERDGenerator()
+        
+        assert generator.models_path == "app/models.py"
+        assert generator.output_path == "../docs/database/erd.mmd"
+        assert generator.generated_models == {}
+        assert generator.model_discovery is not None
+        assert generator.validator is not None
+        assert generator.mermaid_validator is not None
+
+    def test_initialization_custom_paths(self):
+        """Test ERD Generator initialization with custom paths."""
+        generator = ERDGenerator(
+            models_path="custom/models.py",
+            output_path="custom/output.mmd"
+        )
+        
+        assert generator.models_path == "custom/models.py"
+        assert generator.output_path == "custom/output.mmd"
+
+    @patch('app.erd_generator.ModelDiscovery')
+    def test_discover_models(self, mock_discovery):
+        """Test model discovery functionality."""
+        # Setup mock
+        mock_discovery_instance = Mock()
+        mock_discovery_instance.discover_models.return_value = {
+            "User": Mock(),
+            "Item": Mock()
+        }
+        mock_discovery.return_value = mock_discovery_instance
+        
+        generator = ERDGenerator()
+        generator.model_discovery = mock_discovery_instance
+        
+        generator._discover_models()
+        
+        assert len(generator.discovered_models) == 2
+        assert "User" in generator.discovered_models
+        assert "Item" in generator.discovered_models
+
+    def test_extract_model_metadata(self):
+        """Test model metadata extraction."""
+        generator = ERDGenerator()
+        
+        # Mock discovered models
+        mock_user_model = Mock()
+        mock_user_model.__name__ = "User"
+        mock_user_model.__module__ = "app.models"
+        
+        mock_item_model = Mock()
+        mock_item_model.__name__ = "Item"
+        mock_item_model.__module__ = "app.models"
+        
+        generator.discovered_models = {
+            "User": mock_user_model,
+            "Item": mock_item_model
+        }
+        
+        # Mock model discovery extract_metadata method
+        with patch.object(generator.model_discovery, 'extract_metadata') as mock_extract:
+            mock_extract.side_effect = [
+                ModelMetadata(
+                    class_name="User",
+                    table_name="USER",
+                    file_path=Path("app/models.py"),
+                    line_number=10,
+                    fields=[],
+                    relationships=[],
+                    constraints=[]
+                ),
+                ModelMetadata(
+                    class_name="Item", 
+                    table_name="ITEM",
+                    file_path=Path("app/models.py"),
+                    line_number=20,
+                    fields=[],
+                    relationships=[],
+                    constraints=[]
+                )
+            ]
+            
+            generator._extract_model_metadata()
+            
+            assert len(generator.generated_models) == 2
+            assert "User" in generator.generated_models
+            assert "Item" in generator.generated_models
+
+    def test_generate_entities(self):
+        """Test entity generation from model metadata."""
+        generator = ERDGenerator()
+        
+        # Mock generated models
+        user_metadata = ModelMetadata(
+            class_name="User",
+            table_name="USER",
+            file_path=Path("app/models.py"),
+            line_number=10,
+            fields=[
+                FieldMetadata(
+                    name="id",
+                    type_hint="uuid.UUID",
+                    is_primary_key=True
+                ),
+                FieldMetadata(
+                    name="email",
+                    type_hint="str",
+                    is_primary_key=False
+                )
+            ],
+            relationships=[],
+            constraints=[]
+        )
+        
+        generator.generated_models = {"User": user_metadata}
+        
+        entities = generator._generate_entities()
+        
+        assert len(entities) == 1
+        assert entities[0].name == "USER"
+        assert len(entities[0].fields) == 2
+        assert entities[0].fields[0].name == "id"
+        assert entities[0].fields[0].is_primary_key is True
+
+    def test_generate_relationships(self):
+        """Test relationship generation with bidirectional deduplication."""
+        generator = ERDGenerator()
+        
+        # Create mock models with bidirectional relationship
+        user_metadata = ModelMetadata(
+            class_name="User",
+            table_name="USER",
+            file_path=Path("app/models.py"),
+            line_number=10,
+            fields=[],
+            relationships=[
+                RelationshipMetadata(
+                    field_name="items",
+                    target_model="Item",
+                    relationship_type="one-to-many",
+                    back_populates="owner",
+                    foreign_key_field=None,
+                    cascade=None
+                )
+            ],
+            constraints=[]
+        )
+        
+        item_metadata = ModelMetadata(
+            class_name="Item",
+            table_name="ITEM",
+            file_path=Path("app/models.py"),
+            line_number=20,
+            fields=[],
+            relationships=[
+                RelationshipMetadata(
+                    field_name="owner",
+                    target_model="User",
+                    relationship_type="many-to-one",
+                    back_populates="items",
+                    foreign_key_field="owner_id",
+                    cascade=None
+                )
+            ],
+            constraints=[]
+        )
+        
+        generator.generated_models = {
+            "User": user_metadata,
+            "Item": item_metadata
+        }
+        
+        relationships = generator._generate_relationships()
+        
+        # Should only generate one relationship (the one-to-many direction)
+        assert len(relationships) == 1
+        assert relationships[0].from_entity == "USER"
+        assert relationships[0].to_entity == "ITEM"
+        assert relationships[0].relationship_type.value == "1:N"
+
+    def test_is_bidirectional_relationship(self):
+        """Test bidirectional relationship detection."""
+        generator = ERDGenerator()
+        
+        # Create mock relationship metadata
+        user_rel = RelationshipMetadata(
+            field_name="items",
+            target_model="Item",
+            relationship_type="one-to-many",
+            back_populates="owner",
+            foreign_key_field=None,
+            cascade=None
+        )
+        
+        item_rel = RelationshipMetadata(
+            field_name="owner",
+            target_model="User",
+            relationship_type="many-to-one",
+            back_populates="items",
+            foreign_key_field="owner_id",
+            cascade=None
+        )
+        
+        item_model = ModelMetadata(
+            class_name="Item",
+            table_name="ITEM",
+            file_path=Path("app/models.py"),
+            line_number=20,
+            fields=[],
+            relationships=[item_rel],
+            constraints=[]
+        )
+        
+        # Test bidirectional detection
+        is_bidirectional = generator._is_bidirectional_relationship(user_rel, item_model)
+        assert is_bidirectional is True
+        
+        # Test non-bidirectional relationship
+        non_bidirectional_rel = RelationshipMetadata(
+            field_name="other_field",
+            target_model="OtherModel",
+            relationship_type="many-to-one",
+            back_populates=None,
+            foreign_key_field=None,
+            cascade=None
+        )
+        
+        is_bidirectional2 = generator._is_bidirectional_relationship(non_bidirectional_rel, item_model)
+        assert is_bidirectional2 is False
+
+    def test_generate_mermaid_code(self):
+        """Test Mermaid code generation."""
+        generator = ERDGenerator()
+        
+        # Mock entities
+        entities = [
+            EntityDefinition(
+                name="USER",
+                fields=[],
+                description="User entity"
+            ),
+            EntityDefinition(
+                name="ITEM",
+                fields=[],
+                description="Item entity"
+            )
+        ]
+        
+        # Mock relationships
+        relationships = [
+            RelationshipDefinition(
+                from_entity="USER",
+                to_entity="ITEM",
+                relationship_type=None,  # Will be set by the class
+                from_cardinality=None,
+                to_cardinality=None
+            )
+        ]
+        
+        mermaid_code = generator._generate_mermaid_code(entities, relationships)
+        
+        assert "erDiagram" in mermaid_code
+        assert "USER {" in mermaid_code
+        assert "ITEM {" in mermaid_code
+
+    @patch('builtins.open', new_callable=MagicMock)
+    @patch('pathlib.Path.mkdir')
+    def test_write_output(self, mock_mkdir, mock_open):
+        """Test ERD output writing to file."""
+        generator = ERDGenerator()
+        
+        # Mock ERD output
+        erd_output = ERDOutput(
+            mermaid_code="erDiagram\nUSER { id PK }",
+            entities=[],
+            relationships=[],
+            metadata={"generated_at": "2024-01-01T00:00:00"}
+        )
+        
+        generator._write_output(erd_output)
+        
+        # Verify file operations
+        mock_mkdir.assert_called_once_with(parents=True, exist_ok=True)
+        mock_open.assert_called_once()
+
+    @patch.object(ERDGenerator, '_discover_models')
+    @patch.object(ERDGenerator, '_extract_model_metadata')
+    @patch.object(ERDGenerator, '_generate_entities')
+    @patch.object(ERDGenerator, '_generate_relationships')
+    @patch.object(ERDGenerator, '_generate_mermaid_code')
+    @patch.object(ERDGenerator, '_write_output')
+    def test_generate_erd_success(self, mock_write, mock_mermaid, mock_rel, 
+                                 mock_entities, mock_extract, mock_discover):
+        """Test successful ERD generation workflow."""
+        generator = ERDGenerator()
+        
+        # Setup mocks
+        mock_entities.return_value = []
+        mock_rel.return_value = []
+        mock_mermaid.return_value = "erDiagram\nUSER { id PK }"
+        
+        # Mock validator
+        mock_validation_result = Mock()
+        mock_validation_result.is_valid = True
+        mock_validation_result.errors = []
+        mock_validation_result.warnings = []
+        generator.validator.validate_all.return_value = mock_validation_result
+        
+        # Mock mermaid validator
+        mock_mermaid_validation = Mock()
+        mock_mermaid_validation.is_valid = True
+        mock_mermaid_validation.errors = []
+        mock_mermaid_validation.warnings = []
+        generator.mermaid_validator.validate_complete.return_value = mock_mermaid_validation
+        
+        result = generator.generate_erd()
+        
+        # Verify workflow
+        mock_discover.assert_called_once()
+        mock_extract.assert_called_once()
+        mock_entities.assert_called_once()
+        mock_rel.assert_called_once()
+        mock_mermaid.assert_called_once()
+        mock_write.assert_called_once()
+        
+        assert result == "erDiagram\nUSER { id PK }"
+
+    @patch.object(ERDGenerator, '_discover_models')
+    def test_generate_erd_failure(self, mock_discover):
+        """Test ERD generation failure handling."""
+        generator = ERDGenerator()
+        
+        # Mock discovery to raise exception
+        mock_discover.side_effect = Exception("Model discovery failed")
+        
+        with pytest.raises(Exception) as exc_info:
+            generator.generate_erd()
+        
+        assert "ERD generation failed" in str(exc_info.value)
+        assert "Model discovery failed" in str(exc_info.value)
+
+    def test_find_target_model(self):
+        """Test target model finding for foreign key fields."""
+        generator = ERDGenerator()
+        
+        # Test with _id suffix
+        target = generator._find_target_model("owner_id")
+        assert target == "Owner"
+        
+        # Test with user_id suffix
+        target = generator._find_target_model("user_id")
+        assert target == "User"
+        
+        # Test without _id suffix
+        target = generator._find_target_model("name")
+        assert target is None
+
+    def test_is_relationship_field(self):
+        """Test relationship field detection."""
+        generator = ERDGenerator()
+        
+        # Test list type (one-to-many)
+        field_meta = FieldMetadata(
+            name="items",
+            type_hint="list[Item]",
+            is_foreign_key=False
+        )
+        assert generator._is_relationship_field(field_meta) is True
+        
+        # Test union type with None (many-to-one)
+        field_meta = FieldMetadata(
+            name="owner",
+            type_hint="User | None",
+            is_foreign_key=False
+        )
+        assert generator._is_relationship_field(field_meta) is True
+        
+        # Test regular field
+        field_meta = FieldMetadata(
+            name="name",
+            type_hint="str",
+            is_foreign_key=False
+        )
+        assert generator._is_relationship_field(field_meta) is False
+        
+        # Test foreign key field
+        field_meta = FieldMetadata(
+            name="owner_id",
+            type_hint="uuid.UUID",
+            is_foreign_key=True
+        )
+        assert generator._is_relationship_field(field_meta) is False
diff --git a/backend/tests/unit/erd_tests/test_mermaid_validator.py b/backend/tests/unit/erd_tests/test_mermaid_validator.py
new file mode 100644
index 0000000000..8fe622ddbe
--- /dev/null
+++ b/backend/tests/unit/erd_tests/test_mermaid_validator.py
@@ -0,0 +1,211 @@
+"""
+Unit tests for Mermaid ERD syntax validation.
+"""
+
+import pytest
+from pathlib import Path
+
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+from erd import MermaidValidator
+
+
+class TestMermaidValidator:
+    """Test Mermaid syntax validation."""
+
+    def test_valid_erd_syntax(self):
+        """Test validation of valid ERD syntax."""
+        validator = MermaidValidator()
+        
+        valid_erd = """
+erDiagram
+
+USER {
+    uuid id PK
+    string name
+}
+
+ITEM {
+    uuid id PK
+    string title
+    uuid owner_id FK
+}
+
+USER ||--}o ITEM : owns
+"""
+        
+        result = validator.validate_erd_structure(valid_erd)
+        assert result.is_valid
+        assert len(result.errors) == 0
+
+    def test_missing_erdiagram_declaration(self):
+        """Test detection of missing erDiagram declaration."""
+        validator = MermaidValidator()
+        
+        invalid_erd = """
+USER {
+    uuid id PK
+}
+
+ITEM {
+    uuid id PK
+}
+"""
+        
+        result = validator.validate_erd_structure(invalid_erd)
+        assert not result.is_valid
+        assert any("Missing erDiagram declaration" in error.message for error in result.errors)
+
+    def test_no_entities(self):
+        """Test detection of ERD with no entities."""
+        validator = MermaidValidator()
+        
+        invalid_erd = """
+erDiagram
+
+USER ||--}o ITEM : owns
+"""
+        
+        result = validator.validate_erd_structure(invalid_erd)
+        assert not result.is_valid
+        assert any("No entities found" in error.message for error in result.errors)
+
+    def test_invalid_relationship_syntax(self):
+        """Test detection of invalid relationship syntax."""
+        validator = MermaidValidator()
+        
+        invalid_erd = """
+erDiagram
+
+USER {
+    uuid id PK
+}
+
+ITEM {
+    uuid id PK
+}
+
+USER -- ITEM : invalid
+"""
+        
+        result = validator.validate_erd_structure(invalid_erd)
+        assert not result.is_valid
+        assert any("Invalid relationship syntax" in error.message for error in result.errors)
+
+    def test_unmatched_braces(self):
+        """Test detection of unmatched braces."""
+        validator = MermaidValidator()
+        
+        invalid_erd = """
+erDiagram
+
+USER {
+    uuid id PK
+    string name
+"""
+        
+        result = validator.validate_erd_structure(invalid_erd)
+        assert not result.is_valid
+        assert any("Unmatched braces" in error.message for error in result.errors)
+
+    def test_entity_and_relationship_counting(self):
+        """Test accurate counting of entities and relationships."""
+        validator = MermaidValidator()
+        
+        erd = """
+erDiagram
+
+USER {
+    uuid id PK
+    string name
+}
+
+ITEM {
+    uuid id PK
+    string title
+}
+
+CATEGORY {
+    uuid id PK
+    string name
+}
+
+USER ||--}o ITEM : owns
+ITEM }o--|| CATEGORY : belongs_to
+"""
+        
+        result = validator.validate_erd_structure(erd)
+        assert result.is_valid
+        
+        # Check info messages for counts
+        info_messages = [warning.message for warning in result.warnings]
+        assert any("3 entities" in msg for msg in info_messages)
+        assert any("2 relationships" in msg for msg in info_messages)
+
+    def test_mermaid_cli_availability_check(self):
+        """Test Mermaid CLI availability detection."""
+        validator = MermaidValidator()
+        
+        # This test just ensures the method doesn't crash
+        # The actual availability depends on the test environment
+        cli_available = validator.mermaid_cli_available
+        assert isinstance(cli_available, bool)
+
+    def test_complete_validation_workflow(self):
+        """Test complete validation workflow."""
+        validator = MermaidValidator()
+        
+        valid_erd = """
+erDiagram
+
+USER {
+    uuid id PK
+    string name
+}
+
+ITEM {
+    uuid id PK
+    string title
+    uuid owner_id FK
+}
+
+USER ||--}o ITEM : owns
+"""
+        
+        result = validator.validate_complete(valid_erd)
+        
+        # Structure validation should pass
+        assert result.is_valid or len(result.errors) == 0
+        
+        # Should have info about entities and relationships
+        info_messages = [warning.message for warning in result.warnings]
+        assert any("entities" in msg and "relationships" in msg for msg in info_messages)
+
+    def test_validation_with_comments(self):
+        """Test validation with Mermaid comments."""
+        validator = MermaidValidator()
+        
+        erd_with_comments = """
+%% Database ERD Diagram
+%% Generated: 2024-01-01T00:00:00
+
+erDiagram
+
+USER {
+    uuid id PK
+    string name
+}
+
+ITEM {
+    uuid id PK
+    string title
+}
+
+%% User owns many items
+USER ||--}o ITEM : owns
+"""
+        
+        result = validator.validate_erd_structure(erd_with_comments)
+        assert result.is_valid
+        assert len(result.errors) == 0
diff --git a/backend/tests/unit/erd_tests/test_models.py b/backend/tests/unit/erd_tests/test_models.py
new file mode 100644
index 0000000000..b9edb6054a
--- /dev/null
+++ b/backend/tests/unit/erd_tests/test_models.py
@@ -0,0 +1,519 @@
+"""
+Unit tests for ERD Models module.
+
+Tests the data structures used for model metadata, field metadata,
+relationship metadata, and constraint metadata.
+"""
+
+import pytest
+from pathlib import Path
+
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+from erd import (
+    FieldMetadata,
+    RelationshipMetadata,
+    ConstraintMetadata,
+    ModelMetadata
+)
+
+
+class TestFieldMetadata:
+    """Test FieldMetadata data structure."""
+
+    def test_field_metadata_creation(self):
+        """Test FieldMetadata creation with required fields."""
+        field = FieldMetadata(
+            name="id",
+            type_hint="uuid.UUID",
+            is_primary_key=True,
+            is_foreign_key=False,
+            is_nullable=False
+        )
+        
+        assert field.name == "id"
+        assert field.type_hint == "uuid.UUID"
+        assert field.is_primary_key is True
+        assert field.is_foreign_key is False
+        assert field.is_nullable is False
+        assert field.constraints == []
+
+    def test_field_metadata_with_constraints(self):
+        """Test FieldMetadata with constraints."""
+        field = FieldMetadata(
+            name="email",
+            type_hint="str",
+            constraints=["unique", "not_null"]
+        )
+        
+        assert field.constraints == ["unique", "not_null"]
+
+    def test_field_metadata_to_dict(self):
+        """Test FieldMetadata to_dict conversion."""
+        field = FieldMetadata(
+            name="title",
+            type_hint="str",
+            is_primary_key=False,
+            is_foreign_key=False,
+            is_nullable=True,
+            default_value="Untitled"
+        )
+        
+        field_dict = field.to_dict()
+        
+        assert field_dict["name"] == "title"
+        assert field_dict["type_hint"] == "str"
+        assert field_dict["is_primary_key"] is False
+        assert field_dict["is_foreign_key"] is False
+        assert field_dict["is_nullable"] is True
+        assert field_dict["default_value"] == "Untitled"
+
+    def test_field_metadata_post_init(self):
+        """Test FieldMetadata __post_init__ behavior."""
+        field = FieldMetadata(
+            name="id",
+            type_hint="int"
+        )
+        
+        # Should initialize empty constraints list
+        assert field.constraints == []
+
+
+class TestRelationshipMetadata:
+    """Test RelationshipMetadata data structure."""
+
+    def test_relationship_metadata_creation(self):
+        """Test RelationshipMetadata creation."""
+        rel = RelationshipMetadata(
+            field_name="items",
+            target_model="Item",
+            relationship_type="one-to-many",
+            back_populates="owner",
+            foreign_key_field=None,
+            cascade="delete"
+        )
+        
+        assert rel.field_name == "items"
+        assert rel.target_model == "Item"
+        assert rel.relationship_type == "one-to-many"
+        assert rel.back_populates == "owner"
+        assert rel.foreign_key_field is None
+        assert rel.cascade == "delete"
+
+    def test_relationship_metadata_minimal(self):
+        """Test RelationshipMetadata with minimal fields."""
+        rel = RelationshipMetadata(
+            field_name="owner",
+            target_model="User",
+            relationship_type="many-to-one"
+        )
+        
+        assert rel.field_name == "owner"
+        assert rel.target_model == "User"
+        assert rel.relationship_type == "many-to-one"
+        assert rel.back_populates is None
+        assert rel.foreign_key_field is None
+        assert rel.cascade is None
+
+    def test_relationship_metadata_foreign_key(self):
+        """Test RelationshipMetadata with foreign key field."""
+        rel = RelationshipMetadata(
+            field_name="owner",
+            target_model="User",
+            relationship_type="many-to-one",
+            foreign_key_field="owner_id"
+        )
+        
+        assert rel.foreign_key_field == "owner_id"
+
+
+class TestConstraintMetadata:
+    """Test ConstraintMetadata data structure."""
+
+    def test_constraint_metadata_creation(self):
+        """Test ConstraintMetadata creation."""
+        constraint = ConstraintMetadata(
+            name="pk_user",
+            type="primary_key",
+            fields=["id"]
+        )
+        
+        assert constraint.name == "pk_user"
+        assert constraint.type == "primary_key"
+        assert constraint.fields == ["id"]
+        assert constraint.target_table is None
+        assert constraint.target_fields is None
+
+    def test_constraint_metadata_foreign_key(self):
+        """Test ConstraintMetadata for foreign key."""
+        constraint = ConstraintMetadata(
+            name="fk_item_owner",
+            type="foreign_key",
+            fields=["owner_id"],
+            target_table="user",
+            target_fields=["id"]
+        )
+        
+        assert constraint.name == "fk_item_owner"
+        assert constraint.type == "foreign_key"
+        assert constraint.fields == ["owner_id"]
+        assert constraint.target_table == "user"
+        assert constraint.target_fields == ["id"]
+
+    def test_constraint_metadata_unique(self):
+        """Test ConstraintMetadata for unique constraint."""
+        constraint = ConstraintMetadata(
+            name="uk_user_email",
+            type="unique",
+            fields=["email"]
+        )
+        
+        assert constraint.name == "uk_user_email"
+        assert constraint.type == "unique"
+        assert constraint.fields == ["email"]
+
+
+class TestModelMetadata:
+    """Test ModelMetadata data structure."""
+
+    def test_model_metadata_creation(self):
+        """Test ModelMetadata creation."""
+        fields = [
+            FieldMetadata(
+                name="id",
+                type_hint="uuid.UUID",
+                is_primary_key=True
+            ),
+            FieldMetadata(
+                name="email",
+                type_hint="str"
+            )
+        ]
+        
+        relationships = [
+            RelationshipMetadata(
+                field_name="items",
+                target_model="Item",
+                relationship_type="one-to-many"
+            )
+        ]
+        
+        constraints = [
+            ConstraintMetadata(
+                name="pk_user",
+                type="primary_key",
+                fields=["id"]
+            )
+        ]
+        
+        model = ModelMetadata(
+            class_name="User",
+            table_name="USER",
+            file_path=Path("app/models.py"),
+            line_number=10,
+            fields=fields,
+            relationships=relationships,
+            constraints=constraints
+        )
+        
+        assert model.class_name == "User"
+        assert model.table_name == "USER"
+        assert model.file_path == Path("app/models.py")
+        assert model.line_number == 10
+        assert len(model.fields) == 2
+        assert len(model.relationships) == 1
+        assert len(model.constraints) == 1
+        assert model.imports == []
+
+    def test_model_metadata_post_init_primary_key(self):
+        """Test ModelMetadata __post_init__ primary key detection."""
+        fields = [
+            FieldMetadata(
+                name="email",
+                type_hint="str"
+            ),
+            FieldMetadata(
+                name="id",
+                type_hint="uuid.UUID",
+                is_primary_key=True
+            )
+        ]
+        
+        model = ModelMetadata(
+            class_name="User",
+            table_name="USER",
+            file_path=Path("app/models.py"),
+            line_number=10,
+            fields=fields,
+            relationships=[],
+            constraints=[]
+        )
+        
+        # Should auto-detect primary key
+        assert model.primary_key == "id"
+
+    def test_model_metadata_post_init_imports(self):
+        """Test ModelMetadata __post_init__ imports initialization."""
+        model = ModelMetadata(
+            class_name="User",
+            table_name="USER",
+            file_path=Path("app/models.py"),
+            line_number=10,
+            fields=[],
+            relationships=[],
+            constraints=[]
+        )
+        
+        # Should initialize empty imports list
+        assert model.imports == []
+
+    def test_model_metadata_has_foreign_keys(self):
+        """Test ModelMetadata has_foreign_keys property."""
+        # Model with foreign key fields
+        fields_with_fk = [
+            FieldMetadata(
+                name="id",
+                type_hint="uuid.UUID",
+                is_primary_key=True
+            ),
+            FieldMetadata(
+                name="owner_id",
+                type_hint="uuid.UUID",
+                is_foreign_key=True
+            )
+        ]
+        
+        model_with_fk = ModelMetadata(
+            class_name="Item",
+            table_name="ITEM",
+            file_path=Path("app/models.py"),
+            line_number=20,
+            fields=fields_with_fk,
+            relationships=[],
+            constraints=[]
+        )
+        
+        assert model_with_fk.has_foreign_keys is True
+        
+        # Model without foreign key fields
+        fields_without_fk = [
+            FieldMetadata(
+                name="id",
+                type_hint="uuid.UUID",
+                is_primary_key=True
+            ),
+            FieldMetadata(
+                name="name",
+                type_hint="str"
+            )
+        ]
+        
+        model_without_fk = ModelMetadata(
+            class_name="Category",
+            table_name="CATEGORY",
+            file_path=Path("app/models.py"),
+            line_number=30,
+            fields=fields_without_fk,
+            relationships=[],
+            constraints=[]
+        )
+        
+        assert model_without_fk.has_foreign_keys is False
+
+    def test_model_metadata_foreign_key_fields_property(self):
+        """Test ModelMetadata foreign_key_fields property."""
+        fields = [
+            FieldMetadata(
+                name="id",
+                type_hint="uuid.UUID",
+                is_primary_key=True
+            ),
+            FieldMetadata(
+                name="owner_id",
+                type_hint="uuid.UUID",
+                is_foreign_key=True
+            ),
+            FieldMetadata(
+                name="category_id",
+                type_hint="uuid.UUID",
+                is_foreign_key=True
+            ),
+            FieldMetadata(
+                name="name",
+                type_hint="str"
+            )
+        ]
+        
+        model = ModelMetadata(
+            class_name="Item",
+            table_name="ITEM",
+            file_path=Path("app/models.py"),
+            line_number=20,
+            fields=fields,
+            relationships=[],
+            constraints=[]
+        )
+        
+        fk_fields = model.foreign_key_fields
+        assert len(fk_fields) == 2
+        assert fk_fields[0].name == "owner_id"
+        assert fk_fields[1].name == "category_id"
+
+    def test_model_metadata_primary_key_fields_property(self):
+        """Test ModelMetadata primary_key_fields property."""
+        fields = [
+            FieldMetadata(
+                name="id",
+                type_hint="uuid.UUID",
+                is_primary_key=True
+            ),
+            FieldMetadata(
+                name="email",
+                type_hint="str"
+            )
+        ]
+        
+        model = ModelMetadata(
+            class_name="User",
+            table_name="USER",
+            file_path=Path("app/models.py"),
+            line_number=10,
+            fields=fields,
+            relationships=[],
+            constraints=[]
+        )
+        
+        pk_fields = model.primary_key_fields
+        assert len(pk_fields) == 1
+        assert pk_fields[0].name == "id"
+
+    def test_model_metadata_relationship_fields_property(self):
+        """Test ModelMetadata relationship_fields property."""
+        fields = [
+            FieldMetadata(
+                name="id",
+                type_hint="uuid.UUID",
+                is_primary_key=True
+            ),
+            FieldMetadata(
+                name="items",
+                type_hint="list[Item]"
+            ),
+            FieldMetadata(
+                name="owner",
+                type_hint="User | None"
+            ),
+            FieldMetadata(
+                name="name",
+                type_hint="str"
+            )
+        ]
+        
+        model = ModelMetadata(
+            class_name="User",
+            table_name="USER",
+            file_path=Path("app/models.py"),
+            line_number=10,
+            fields=fields,
+            relationships=[],
+            constraints=[]
+        )
+        
+        rel_fields = model.relationship_fields
+        assert len(rel_fields) == 2
+        assert rel_fields[0].name == "items"
+        assert rel_fields[1].name == "owner"
+
+    def test_model_metadata_to_dict(self):
+        """Test ModelMetadata to_dict conversion."""
+        fields = [
+            FieldMetadata(
+                name="id",
+                type_hint="uuid.UUID",
+                is_primary_key=True
+            )
+        ]
+        
+        model = ModelMetadata(
+            class_name="User",
+            table_name="USER",
+            file_path=Path("app/models.py"),
+            line_number=10,
+            fields=fields,
+            relationships=[],
+            constraints=[],
+            primary_key="id"
+        )
+        
+        model_dict = model.to_dict()
+        
+        assert model_dict["class_name"] == "User"
+        assert model_dict["table_name"] == "USER"
+        assert model_dict["primary_key"] == "id"
+        assert len(model_dict["fields"]) == 1
+        assert model_dict["fields"][0]["name"] == "id"
+
+    def test_model_metadata_get_field_by_name(self):
+        """Test ModelMetadata get_field_by_name method."""
+        fields = [
+            FieldMetadata(
+                name="id",
+                type_hint="uuid.UUID",
+                is_primary_key=True
+            ),
+            FieldMetadata(
+                name="email",
+                type_hint="str"
+            )
+        ]
+        
+        model = ModelMetadata(
+            class_name="User",
+            table_name="USER",
+            file_path=Path("app/models.py"),
+            line_number=10,
+            fields=fields,
+            relationships=[],
+            constraints=[]
+        )
+        
+        # Test existing field
+        field = model.get_field_by_name("email")
+        assert field is not None
+        assert field.name == "email"
+        
+        # Test non-existing field
+        field = model.get_field_by_name("nonexistent")
+        assert field is None
+
+    def test_model_metadata_has_field(self):
+        """Test ModelMetadata has_field method."""
+        fields = [
+            FieldMetadata(
+                name="id",
+                type_hint="uuid.UUID",
+                is_primary_key=True
+            ),
+            FieldMetadata(
+                name="email",
+                type_hint="str"
+            )
+        ]
+        
+        model = ModelMetadata(
+            class_name="User",
+            table_name="USER",
+            file_path=Path("app/models.py"),
+            line_number=10,
+            fields=fields,
+            relationships=[],
+            constraints=[]
+        )
+        
+        # Test existing field
+        assert model.has_field("email") is True
+        assert model.has_field("id") is True
+        
+        # Test non-existing field
+        assert model.has_field("nonexistent") is False
diff --git a/backend/tests/unit/erd_tests/test_relationships.py b/backend/tests/unit/erd_tests/test_relationships.py
new file mode 100644
index 0000000000..6291214533
--- /dev/null
+++ b/backend/tests/unit/erd_tests/test_relationships.py
@@ -0,0 +1,258 @@
+"""
+Unit tests for ERD relationship detection and rendering.
+"""
+
+import pytest
+from pathlib import Path
+import tempfile
+import os
+
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+from erd import (
+    RelationshipDefinition,
+    RelationshipManager,
+    RelationshipType,
+    Cardinality,
+    ModelDiscovery,
+    RelationshipMetadata,
+)
+
+
+class TestRelationshipDetection:
+    """Test relationship detection from SQLModel definitions."""
+
+    def test_parse_relationship_from_source(self):
+        """Test parsing Relationship() calls from source code."""
+        # Create temporary model file with relationships
+        model_content = '''
+from sqlmodel import SQLModel, Field, Relationship
+import uuid
+
+class User(SQLModel, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    name: str
+    items: list["Item"] = Relationship(back_populates="owner", cascade_delete=True)
+
+class Item(SQLModel, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    title: str
+    owner_id: uuid.UUID = Field(foreign_key="user.id")
+    owner: User | None = Relationship(back_populates="items")
+'''
+        
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.py', delete=False) as f:
+            f.write(model_content)
+            temp_file = f.name
+        
+        try:
+            discovery = ModelDiscovery()
+            relationships = discovery._parse_relationships_from_source(Path(temp_file), "User")
+            
+            # Should detect the items relationship
+            assert len(relationships) >= 1
+            
+            items_rel = next((r for r in relationships if r.field_name == "items"), None)
+            assert items_rel is not None
+            assert items_rel.target_model == "Item"
+            assert items_rel.back_populates == "owner"
+            assert items_rel.cascade_delete is True
+            
+        finally:
+            os.unlink(temp_file)
+
+    def test_relationship_type_detection(self):
+        """Test detection of different relationship types."""
+        # Test one-to-many relationship
+        rel_meta = RelationshipMetadata(
+            field_name="items",
+            target_model="Item",
+            relationship_type="one-to-many",
+            back_populates="owner"
+        )
+        
+        relationship = RelationshipDefinition.from_model_relationship(
+            rel_meta, 
+            {"table_name": "user"}, 
+            {"table_name": "item"}
+        )
+        
+        assert relationship.relationship_type == RelationshipType.ONE_TO_MANY
+        assert relationship.from_cardinality == Cardinality.ONE
+        assert relationship.to_cardinality == Cardinality.ZERO_OR_MORE
+
+    def test_mermaid_relationship_rendering(self):
+        """Test Mermaid relationship syntax generation."""
+        relationship = RelationshipDefinition(
+            from_entity="USER",
+            to_entity="ITEM",
+            relationship_type=RelationshipType.ONE_TO_MANY,
+            from_cardinality=Cardinality.ONE,
+            to_cardinality=Cardinality.ZERO_OR_MORE,
+            label="items -> owner"
+        )
+        
+        mermaid_syntax = relationship.to_mermaid_relationship()
+        expected = 'USER ||--o{ ITEM : items -> owner'
+        assert mermaid_syntax == expected
+
+    def test_relationship_manager(self):
+        """Test relationship manager functionality."""
+        manager = RelationshipManager()
+        
+        rel1 = RelationshipDefinition(
+            from_entity="USER",
+            to_entity="ITEM",
+            relationship_type=RelationshipType.ONE_TO_MANY,
+            from_cardinality=Cardinality.ONE,
+            to_cardinality=Cardinality.ZERO_OR_MORE
+        )
+        
+        manager.add_relationship(rel1)
+        
+        # Test getting relationships for entity
+        user_rels = manager.get_relationships_for_entity("USER")
+        assert len(user_rels) == 1
+        
+        item_rels = manager.get_relationships_for_entity("ITEM")
+        assert len(item_rels) == 1
+        
+        # Test outgoing relationships
+        outgoing = manager.get_outgoing_relationships("USER")
+        assert len(outgoing) == 1
+        assert outgoing[0].to_entity == "ITEM"
+        
+        # Test incoming relationships
+        incoming = manager.get_incoming_relationships("ITEM")
+        assert len(incoming) == 1
+        assert incoming[0].from_entity == "USER"
+
+    def test_bidirectional_relationship_detection(self):
+        """Test detection of bidirectional relationships."""
+        discovery = ModelDiscovery()
+        
+        # Mock model classes with bidirectional relationship
+        model_classes = [
+            {
+                "name": "User",
+                "relationships": [
+                    RelationshipMetadata(
+                        field_name="items",
+                        target_model="Item",
+                        relationship_type="one-to-many",
+                        back_populates="owner"
+                    )
+                ]
+            },
+            {
+                "name": "Item", 
+                "relationships": [
+                    RelationshipMetadata(
+                        field_name="owner",
+                        target_model="User",
+                        relationship_type="many-to-one",
+                        back_populates="items"
+                    )
+                ]
+            }
+        ]
+        
+        all_relationships = discovery._resolve_bidirectional_relationships(model_classes)
+        
+        # Both relationships should be marked as bidirectional
+        user_rel = all_relationships["User"][0]
+        item_rel = all_relationships["Item"][0]
+        
+        assert user_rel.is_bidirectional is True
+        assert item_rel.is_bidirectional is True
+
+
+class TestERDWithRelationships:
+    """Test full ERD generation with relationships."""
+
+    def test_erd_generation_with_relationships(self):
+        """Test that ERD generation includes relationship lines."""
+        from app.erd_generator import ERDGenerator
+        
+        # Create temporary model file
+        model_content = '''
+from sqlmodel import SQLModel, Field, Relationship
+import uuid
+
+class User(SQLModel, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    name: str
+    items: list["Item"] = Relationship(back_populates="owner")
+
+class Item(SQLModel, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    title: str
+    owner_id: uuid.UUID = Field(foreign_key="user.id")
+    owner: User | None = Relationship(back_populates="items")
+'''
+        
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.py', delete=False) as f:
+            f.write(model_content)
+            temp_file = f.name
+        
+        try:
+            generator = ERDGenerator(models_path=temp_file)
+            mermaid_code = generator.generate_erd()
+            
+            # Should contain relationship line
+            assert "USER ||--o{ ITEM" in mermaid_code or "ITEM }o--|| USER" in mermaid_code
+            # Should not include relationship fields as regular fields
+            assert "string items" not in mermaid_code
+            assert "string owner" not in mermaid_code
+            
+        finally:
+            os.unlink(temp_file)
+
+    def test_relationship_field_filtering(self):
+        """Test that relationship fields are filtered from entity field lists."""
+        from app.erd_generator import ERDGenerator
+        
+        # Create temporary model file with relationship fields
+        model_content = '''
+from sqlmodel import SQLModel, Field, Relationship
+import uuid
+
+class User(SQLModel, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    name: str
+    items: list["Item"] = Relationship(back_populates="owner")
+
+class Item(SQLModel, table=True):
+    id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+    title: str
+    owner_id: uuid.UUID = Field(foreign_key="user.id")
+    owner: User | None = Relationship(back_populates="items")
+'''
+        
+        with tempfile.NamedTemporaryFile(mode='w', suffix='.py', delete=False) as f:
+            f.write(model_content)
+            temp_file = f.name
+        
+        try:
+            generator = ERDGenerator(models_path=temp_file)
+            generator._discover_models()
+            generator._extract_model_metadata()
+            
+            # Check that relationship fields are not in the field lists
+            user_metadata = generator.generated_models["User"]
+            item_metadata = generator.generated_models["Item"]
+            
+            user_field_names = [f.name for f in user_metadata.fields]
+            item_field_names = [f.name for f in item_metadata.fields]
+            
+            # Relationship fields should not be in regular field lists
+            assert "items" not in user_field_names
+            assert "owner" not in item_field_names
+            
+            # But they should be in relationship lists
+            assert len(user_metadata.relationships) >= 1
+            assert len(item_metadata.relationships) >= 1
+            
+        finally:
+            os.unlink(temp_file)
diff --git a/backend/tests/unit/erd_tests/test_validation.py b/backend/tests/unit/erd_tests/test_validation.py
new file mode 100644
index 0000000000..f784e764b0
--- /dev/null
+++ b/backend/tests/unit/erd_tests/test_validation.py
@@ -0,0 +1,493 @@
+"""
+Unit tests for ERD Validation module.
+
+Tests the validation system for ERD generation including
+model validation, ERD validation, and error handling.
+"""
+
+import pytest
+from unittest.mock import Mock, patch
+
+import sys
+from pathlib import Path
+sys.path.insert(0, str(Path(__file__).parent.parent.parent))
+from erd import ERDValidator, ValidationResult, ValidationError, ErrorSeverity, ModelMetadata, FieldMetadata, RelationshipMetadata
+
+
+class TestValidationError:
+    """Test ValidationError data structure."""
+
+    def test_validation_error_creation(self):
+        """Test ValidationError creation."""
+        error = ValidationError(
+            message="Test error message",
+            severity="error",
+            line_number=10,
+            error_code="ERR001"
+        )
+        
+        assert error.message == "Test error message"
+        assert error.severity == "error"
+        assert error.line_number == 10
+        assert error.error_code == "ERR001"
+
+    def test_validation_error_to_dict(self):
+        """Test ValidationError to_dict conversion."""
+        error = ValidationError(
+            message="Test error",
+            severity="error",
+            line_number=5,
+            error_code="ERR002"
+        )
+        
+        error_dict = error.to_dict()
+        
+        assert error_dict["message"] == "Test error"
+        assert error_dict["severity"] == "error"
+        assert error_dict["line_number"] == 5
+        assert error_dict["error_code"] == "ERR002"
+
+
+
+
+class TestValidationResult:
+    """Test ValidationResult data structure."""
+
+    def test_validation_result_creation(self):
+        """Test ValidationResult creation."""
+        result = ValidationResult()
+        
+        assert result.is_valid is True
+        assert result.errors == []
+        assert result.warnings == []
+
+    def test_validation_result_with_errors(self):
+        """Test ValidationResult with errors."""
+        error = ValidationError(
+            message="Test error",
+            severity="error",
+            line_number=10,
+            error_code="ERR001"
+        )
+        
+        result = ValidationResult()
+        result.add_error(error)
+        
+        assert result.is_valid is False
+        assert len(result.errors) == 1
+        assert result.errors[0] == error
+
+    def test_validation_result_with_warnings(self):
+        """Test ValidationResult with warnings."""
+        warning = ValidationError(
+            message="Test warning",
+            severity=ErrorSeverity.WARNING,
+            line_number=15,
+            error_code="WARN001"
+        )
+        
+        result = ValidationResult()
+        result.add_warning(warning)
+        
+        assert result.is_valid is True  # Warnings don't make result invalid
+        assert len(result.warnings) == 1
+        assert result.warnings[0] == warning
+
+    def test_validation_result_to_dict(self):
+        """Test ValidationResult to_dict conversion."""
+        error = ValidationError(
+            message="Test error",
+            severity="error",
+            line_number=10,
+            error_code="ERR001"
+        )
+        
+        warning = ValidationError(
+            message="Test warning",
+            severity=ErrorSeverity.WARNING,
+            line_number=15,
+            error_code="WARN001"
+        )
+        
+        result = ValidationResult()
+        result.add_error(error)
+        result.add_warning(warning)
+        
+        result_dict = result.to_dict()
+        
+        assert result_dict["is_valid"] is False
+        assert len(result_dict["errors"]) == 1
+        assert len(result_dict["warnings"]) == 1
+        assert result_dict["errors"][0]["message"] == "Test error"
+        assert result_dict["warnings"][0]["message"] == "Test warning"
+
+
+class TestERDValidator:
+    """Test ERDValidator functionality."""
+
+    def test_validator_initialization(self):
+        """Test ERDValidator initialization."""
+        validator = ERDValidator()
+        
+        assert validator is not None
+
+    def test_validate_model_metadata_success(self):
+        """Test successful model metadata validation."""
+        validator = ERDValidator()
+        
+        # Create valid model metadata
+        fields = [
+            FieldMetadata(
+                name="id",
+                type_hint="uuid.UUID",
+                is_primary_key=True
+            ),
+            FieldMetadata(
+                name="email",
+                type_hint="str"
+            )
+        ]
+        
+        model = ModelMetadata(
+            class_name="User",
+            table_name="USER",
+            file_path=None,
+            line_number=10,
+            fields=fields,
+            relationships=[],
+            constraints=[]
+        )
+        
+        result = validator.validate_model_metadata(model)
+        
+        assert result.is_valid is True
+        assert len(result.errors) == 0
+
+    def test_validate_model_metadata_no_primary_key(self):
+        """Test model metadata validation without primary key."""
+        validator = ERDValidator()
+        
+        # Create model without primary key
+        fields = [
+            FieldMetadata(
+                name="name",
+                type_hint="str"
+            )
+        ]
+        
+        model = ModelMetadata(
+            class_name="User",
+            table_name="USER",
+            file_path=None,
+            line_number=10,
+            fields=fields,
+            relationships=[],
+            constraints=[]
+        )
+        
+        result = validator.validate_model_metadata(model)
+        
+        assert result.is_valid is False
+        assert len(result.errors) == 1
+        assert "primary key" in result.errors[0].message.lower()
+
+    def test_validate_model_metadata_empty_fields(self):
+        """Test model metadata validation with empty fields."""
+        validator = ERDValidator()
+        
+        # Create model with no fields
+        model = ModelMetadata(
+            class_name="User",
+            table_name="USER",
+            file_path=None,
+            line_number=10,
+            fields=[],
+            relationships=[],
+            constraints=[]
+        )
+        
+        result = validator.validate_model_metadata(model)
+        
+        assert result.is_valid is False
+        assert len(result.errors) == 1
+        assert "no fields" in result.errors[0].message.lower()
+
+    def test_validate_erd_syntax_success(self):
+        """Test successful ERD syntax validation."""
+        validator = ERDValidator()
+        
+        # Valid Mermaid ERD syntax
+        erd_syntax = """erDiagram
+    USER {
+        uuid id PK
+        string email
+    }
+    
+    ITEM {
+        uuid id PK
+        uuid owner_id FK
+    }
+    
+    USER ||--o{ ITEM : owns"""
+        
+        result = validator.validate_erd_syntax(erd_syntax)
+        
+        assert result.is_valid is True
+        assert len(result.errors) == 0
+
+    def test_validate_erd_syntax_missing_erdiagram(self):
+        """Test ERD syntax validation with missing erDiagram declaration."""
+        validator = ERDValidator()
+        
+        # Invalid syntax - missing erDiagram
+        erd_syntax = """USER {
+        uuid id PK
+    }"""
+        
+        result = validator.validate_erd_syntax(erd_syntax)
+        
+        assert result.is_valid is False
+        assert len(result.errors) == 1
+        assert "erDiagram" in result.errors[0].message
+
+    def test_validate_erd_syntax_no_entities(self):
+        """Test ERD syntax validation with no entities."""
+        validator = ERDValidator()
+        
+        # Valid syntax but no entities
+        erd_syntax = "erDiagram"
+        
+        result = validator.validate_erd_syntax(erd_syntax)
+        
+        assert result.is_valid is False
+        assert len(result.errors) == 1
+        assert "no entities" in result.errors[0].message.lower()
+
+    def test_validate_erd_syntax_invalid_relationship(self):
+        """Test ERD syntax validation with invalid relationship syntax."""
+        validator = ERDValidator()
+        
+        # Invalid relationship syntax
+        erd_syntax = """erDiagram
+    USER {
+        uuid id PK
+    }
+    
+    USER -- ITEM : invalid"""
+        
+        result = validator.validate_erd_syntax(erd_syntax)
+        
+        assert result.is_valid is False
+        assert len(result.errors) >= 1
+        assert any("relationship" in error.message.lower() for error in result.errors)
+
+    def test_validate_erd_syntax_unmatched_braces(self):
+        """Test ERD syntax validation with unmatched braces."""
+        validator = ERDValidator()
+        
+        # Unmatched braces
+        erd_syntax = """erDiagram
+    USER {
+        uuid id PK
+        string email"""
+        
+        result = validator.validate_erd_syntax(erd_syntax)
+        
+        assert result.is_valid is False
+        assert len(result.errors) == 1
+        assert "brace" in result.errors[0].message.lower()
+
+    def test_validate_all_success(self):
+        """Test validate_all method with valid ERD."""
+        validator = ERDValidator()
+        
+        # Valid ERD syntax
+        erd_syntax = """erDiagram
+    USER {
+        uuid id PK
+        string email
+    }"""
+        
+        result = validator.validate_all(erd_syntax)
+        
+        assert result.is_valid is True
+        assert len(result.errors) == 0
+
+    def test_validate_all_with_errors(self):
+        """Test validate_all method with invalid ERD."""
+        validator = ERDValidator()
+        
+        # Invalid ERD syntax
+        erd_syntax = """USER {
+        uuid id PK
+    }"""
+        
+        result = validator.validate_all(erd_syntax)
+        
+        assert result.is_valid is False
+        assert len(result.errors) >= 1
+
+    def test_validate_entities_exist(self):
+        """Test validation that entities exist in ERD."""
+        validator = ERDValidator()
+        
+        # ERD with entities
+        erd_syntax = """erDiagram
+    USER {
+        uuid id PK
+    }
+    
+    ITEM {
+        uuid id PK
+    }"""
+        
+        result = validator.validate_entities_exist(erd_syntax)
+        
+        assert result.is_valid is True
+        assert len(result.errors) == 0
+
+    def test_validate_entities_exist_no_entities(self):
+        """Test validation when no entities exist."""
+        validator = ERDValidator()
+        
+        # ERD without entities
+        erd_syntax = "erDiagram"
+        
+        result = validator.validate_entities_exist(erd_syntax)
+        
+        assert result.is_valid is False
+        assert len(result.errors) == 1
+        assert "no entities" in result.errors[0].message.lower()
+
+    def test_validate_relationships_exist(self):
+        """Test validation that relationships exist in ERD."""
+        validator = ERDValidator()
+        
+        # ERD with relationships
+        erd_syntax = """erDiagram
+    USER {
+        uuid id PK
+    }
+    
+    ITEM {
+        uuid id PK
+    }
+    
+    USER ||--o{ ITEM : owns"""
+        
+        result = validator.validate_relationships_exist(erd_syntax)
+        
+        assert result.is_valid is True
+        assert len(result.errors) == 0
+
+    def test_validate_relationships_exist_no_relationships(self):
+        """Test validation when no relationships exist."""
+        validator = ERDValidator()
+        
+        # ERD without relationships
+        erd_syntax = """erDiagram
+    USER {
+        uuid id PK
+    }"""
+        
+        result = validator.validate_relationships_exist(erd_syntax)
+        
+        # This should be valid (entities can exist without relationships)
+        assert result.is_valid is True
+        assert len(result.errors) == 0
+
+    def test_validate_mermaid_syntax_basic(self):
+        """Test basic Mermaid syntax validation."""
+        validator = ERDValidator()
+        
+        # Valid basic syntax
+        erd_syntax = """erDiagram
+    USER {
+        uuid id PK
+    }"""
+        
+        result = validator.validate_mermaid_syntax(erd_syntax)
+        
+        assert result.is_valid is True
+        assert len(result.errors) == 0
+
+    def test_validate_mermaid_syntax_complex(self):
+        """Test complex Mermaid syntax validation."""
+        validator = ERDValidator()
+        
+        # Complex but valid syntax
+        erd_syntax = """erDiagram
+    USER {
+        uuid id PK
+        string email UK
+        boolean is_active
+    }
+    
+    ITEM {
+        uuid id PK
+        string title
+        uuid owner_id FK
+    }
+    
+    USER ||--o{ ITEM : owns
+    USER }o--|| ITEM : created_by"""
+        
+        result = validator.validate_mermaid_syntax(erd_syntax)
+        
+        assert result.is_valid is True
+        assert len(result.errors) == 0
+
+    def test_count_entities_in_erd(self):
+        """Test entity counting in ERD."""
+        validator = ERDValidator()
+        
+        # ERD with 2 entities
+        erd_syntax = """erDiagram
+    USER {
+        uuid id PK
+    }
+    
+    ITEM {
+        uuid id PK
+    }"""
+        
+        count = validator._count_entities_in_erd(erd_syntax)
+        assert count == 2
+
+    def test_count_relationships_in_erd(self):
+        """Test relationship counting in ERD."""
+        validator = ERDValidator()
+        
+        # ERD with 1 relationship
+        erd_syntax = """erDiagram
+    USER {
+        uuid id PK
+    }
+    
+    ITEM {
+        uuid id PK
+    }
+    
+    USER ||--o{ ITEM : owns"""
+        
+        count = validator._count_relationships_in_erd(erd_syntax)
+        assert count == 1
+
+    def test_extract_entity_names(self):
+        """Test entity name extraction from ERD."""
+        validator = ERDValidator()
+        
+        # ERD with 2 entities
+        erd_syntax = """erDiagram
+    USER {
+        uuid id PK
+    }
+    
+    ITEM {
+        uuid id PK
+    }"""
+        
+        entities = validator._extract_entity_names(erd_syntax)
+        assert len(entities) == 2
+        assert "USER" in entities
+        assert "ITEM" in entities
diff --git a/backend/uv.lock b/backend/uv.lock
index 87182ec90a..f353346497 100644
--- a/backend/uv.lock
+++ b/backend/uv.lock
@@ -70,10 +70,12 @@ dependencies = [
 
 [package.dev-dependencies]
 dev = [
+    { name = "black" },
     { name = "coverage" },
     { name = "mypy" },
     { name = "pre-commit" },
     { name = "pytest" },
+    { name = "pytest-cov" },
     { name = "ruff" },
     { name = "types-passlib" },
 ]
@@ -100,10 +102,12 @@ requires-dist = [
 
 [package.metadata.requires-dev]
 dev = [
+    { name = "black", specifier = ">=25.9.0" },
     { name = "coverage", specifier = ">=7.4.3,<8.0.0" },
     { name = "mypy", specifier = ">=1.8.0,<2.0.0" },
     { name = "pre-commit", specifier = ">=3.6.2,<4.0.0" },
     { name = "pytest", specifier = ">=7.4.3,<8.0.0" },
+    { name = "pytest-cov", specifier = ">=6.3.0" },
     { name = "ruff", specifier = ">=0.2.2,<1.0.0" },
     { name = "types-passlib", specifier = ">=1.7.7.20240106,<2.0.0.0" },
 ]
@@ -166,6 +170,41 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/63/13/47bba97924ebe86a62ef83dc75b7c8a881d53c535f83e2c54c4bd701e05c/bcrypt-4.3.0-pp311-pypy311_pp73-manylinux_2_34_x86_64.whl", hash = "sha256:57967b7a28d855313a963aaea51bf6df89f833db4320da458e5b3c5ab6d4c938", size = 280110, upload-time = "2025-02-28T01:24:05.896Z" },
 ]
 
+[[package]]
+name = "black"
+version = "25.9.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "click" },
+    { name = "mypy-extensions" },
+    { name = "packaging" },
+    { name = "pathspec" },
+    { name = "platformdirs" },
+    { name = "pytokens" },
+    { name = "tomli", marker = "python_full_version < '3.11'" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/4b/43/20b5c90612d7bdb2bdbcceeb53d588acca3bb8f0e4c5d5c751a2c8fdd55a/black-25.9.0.tar.gz", hash = "sha256:0474bca9a0dd1b51791fcc507a4e02078a1c63f6d4e4ae5544b9848c7adfb619", size = 648393, upload-time = "2025-09-19T00:27:37.758Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/25/40/dbe31fc56b218a858c8fc6f5d8d3ba61c1fa7e989d43d4a4574b8b992840/black-25.9.0-cp310-cp310-macosx_10_9_x86_64.whl", hash = "sha256:ce41ed2614b706fd55fd0b4a6909d06b5bab344ffbfadc6ef34ae50adba3d4f7", size = 1715605, upload-time = "2025-09-19T00:36:13.483Z" },
+    { url = "https://files.pythonhosted.org/packages/92/b2/f46800621200eab6479b1f4c0e3ede5b4c06b768e79ee228bc80270bcc74/black-25.9.0-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:2ab0ce111ef026790e9b13bd216fa7bc48edd934ffc4cbf78808b235793cbc92", size = 1571829, upload-time = "2025-09-19T00:32:42.13Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/64/5c7f66bd65af5c19b4ea86062bb585adc28d51d37babf70969e804dbd5c2/black-25.9.0-cp310-cp310-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:f96b6726d690c96c60ba682955199f8c39abc1ae0c3a494a9c62c0184049a713", size = 1631888, upload-time = "2025-09-19T00:30:54.212Z" },
+    { url = "https://files.pythonhosted.org/packages/3b/64/0b9e5bfcf67db25a6eef6d9be6726499a8a72ebab3888c2de135190853d3/black-25.9.0-cp310-cp310-win_amd64.whl", hash = "sha256:d119957b37cc641596063cd7db2656c5be3752ac17877017b2ffcdb9dfc4d2b1", size = 1327056, upload-time = "2025-09-19T00:31:08.877Z" },
+    { url = "https://files.pythonhosted.org/packages/b7/f4/7531d4a336d2d4ac6cc101662184c8e7d068b548d35d874415ed9f4116ef/black-25.9.0-cp311-cp311-macosx_10_9_x86_64.whl", hash = "sha256:456386fe87bad41b806d53c062e2974615825c7a52159cde7ccaeb0695fa28fa", size = 1698727, upload-time = "2025-09-19T00:31:14.264Z" },
+    { url = "https://files.pythonhosted.org/packages/28/f9/66f26bfbbf84b949cc77a41a43e138d83b109502cd9c52dfc94070ca51f2/black-25.9.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:a16b14a44c1af60a210d8da28e108e13e75a284bf21a9afa6b4571f96ab8bb9d", size = 1555679, upload-time = "2025-09-19T00:31:29.265Z" },
+    { url = "https://files.pythonhosted.org/packages/bf/59/61475115906052f415f518a648a9ac679d7afbc8da1c16f8fdf68a8cebed/black-25.9.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:aaf319612536d502fdd0e88ce52d8f1352b2c0a955cc2798f79eeca9d3af0608", size = 1617453, upload-time = "2025-09-19T00:30:42.24Z" },
+    { url = "https://files.pythonhosted.org/packages/7f/5b/20fd5c884d14550c911e4fb1b0dae00d4abb60a4f3876b449c4d3a9141d5/black-25.9.0-cp311-cp311-win_amd64.whl", hash = "sha256:c0372a93e16b3954208417bfe448e09b0de5cc721d521866cd9e0acac3c04a1f", size = 1333655, upload-time = "2025-09-19T00:30:56.715Z" },
+    { url = "https://files.pythonhosted.org/packages/fb/8e/319cfe6c82f7e2d5bfb4d3353c6cc85b523d677ff59edc61fdb9ee275234/black-25.9.0-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:1b9dc70c21ef8b43248f1d86aedd2aaf75ae110b958a7909ad8463c4aa0880b0", size = 1742012, upload-time = "2025-09-19T00:33:08.678Z" },
+    { url = "https://files.pythonhosted.org/packages/94/cc/f562fe5d0a40cd2a4e6ae3f685e4c36e365b1f7e494af99c26ff7f28117f/black-25.9.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:8e46eecf65a095fa62e53245ae2795c90bdecabd53b50c448d0a8bcd0d2e74c4", size = 1581421, upload-time = "2025-09-19T00:35:25.937Z" },
+    { url = "https://files.pythonhosted.org/packages/84/67/6db6dff1ebc8965fd7661498aea0da5d7301074b85bba8606a28f47ede4d/black-25.9.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9101ee58ddc2442199a25cb648d46ba22cd580b00ca4b44234a324e3ec7a0f7e", size = 1655619, upload-time = "2025-09-19T00:30:49.241Z" },
+    { url = "https://files.pythonhosted.org/packages/10/10/3faef9aa2a730306cf469d76f7f155a8cc1f66e74781298df0ba31f8b4c8/black-25.9.0-cp312-cp312-win_amd64.whl", hash = "sha256:77e7060a00c5ec4b3367c55f39cf9b06e68965a4f2e61cecacd6d0d9b7ec945a", size = 1342481, upload-time = "2025-09-19T00:31:29.625Z" },
+    { url = "https://files.pythonhosted.org/packages/48/99/3acfea65f5e79f45472c45f87ec13037b506522719cd9d4ac86484ff51ac/black-25.9.0-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:0172a012f725b792c358d57fe7b6b6e8e67375dd157f64fa7a3097b3ed3e2175", size = 1742165, upload-time = "2025-09-19T00:34:10.402Z" },
+    { url = "https://files.pythonhosted.org/packages/3a/18/799285282c8236a79f25d590f0222dbd6850e14b060dfaa3e720241fd772/black-25.9.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:3bec74ee60f8dfef564b573a96b8930f7b6a538e846123d5ad77ba14a8d7a64f", size = 1581259, upload-time = "2025-09-19T00:32:49.685Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/ce/883ec4b6303acdeca93ee06b7622f1fa383c6b3765294824165d49b1a86b/black-25.9.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b756fc75871cb1bcac5499552d771822fd9db5a2bb8db2a7247936ca48f39831", size = 1655583, upload-time = "2025-09-19T00:30:44.505Z" },
+    { url = "https://files.pythonhosted.org/packages/21/17/5c253aa80a0639ccc427a5c7144534b661505ae2b5a10b77ebe13fa25334/black-25.9.0-cp313-cp313-win_amd64.whl", hash = "sha256:846d58e3ce7879ec1ffe816bb9df6d006cd9590515ed5d17db14e17666b2b357", size = 1343428, upload-time = "2025-09-19T00:32:13.839Z" },
+    { url = "https://files.pythonhosted.org/packages/1b/46/863c90dcd3f9d41b109b7f19032ae0db021f0b2a81482ba0a1e28c84de86/black-25.9.0-py3-none-any.whl", hash = "sha256:474b34c1342cdc157d307b56c4c65bce916480c4a8f6551fdc6bf9b486a7c4ae", size = 203363, upload-time = "2025-09-19T00:27:35.724Z" },
+]
+
 [[package]]
 name = "cachetools"
 version = "5.5.0"
@@ -336,6 +375,11 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/a5/2b/0354ed096bca64dc8e32a7cbcae28b34cb5ad0b1fe2125d6d99583313ac0/coverage-7.6.1-pp38.pp39.pp310-none-any.whl", hash = "sha256:e9a6e0eb86070e8ccaedfbd9d38fec54864f3125ab95419970575b42af7541df", size = 198926, upload-time = "2024-08-04T19:45:28.875Z" },
 ]
 
+[package.optional-dependencies]
+toml = [
+    { name = "tomli", marker = "python_full_version <= '3.11'" },
+]
+
 [[package]]
 name = "cssselect"
 version = "1.2.0"
@@ -853,6 +897,15 @@ bcrypt = [
     { name = "bcrypt" },
 ]
 
+[[package]]
+name = "pathspec"
+version = "0.12.1"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/ca/bc/f35b8446f4531a7cb215605d100cd88b7ac6f44ab3fc94870c120ab3adbf/pathspec-0.12.1.tar.gz", hash = "sha256:a482d51503a1ab33b1c67a6c3813a26953dbdc71c31dacaef9a838c4e29f5712", size = 51043, upload-time = "2023-12-10T22:30:45Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/cc/20/ff623b09d963f88bfde16306a54e12ee5ea43e9b597108672ff3a408aad6/pathspec-0.12.1-py3-none-any.whl", hash = "sha256:a0d503e138a4c123b27490a4f7beda6a01c6f288df0e4a8b79c7eb0dc7b4cc08", size = 31191, upload-time = "2023-12-10T22:30:43.14Z" },
+]
+
 [[package]]
 name = "platformdirs"
 version = "4.3.6"
@@ -1123,6 +1176,20 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/51/ff/f6e8b8f39e08547faece4bd80f89d5a8de68a38b2d179cc1c4490ffa3286/pytest-7.4.4-py3-none-any.whl", hash = "sha256:b090cdf5ed60bf4c45261be03239c2c1c22df034fbffe691abe93cd80cea01d8", size = 325287, upload-time = "2023-12-31T12:00:13.963Z" },
 ]
 
+[[package]]
+name = "pytest-cov"
+version = "6.3.0"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "coverage", extra = ["toml"] },
+    { name = "pluggy" },
+    { name = "pytest" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/30/4c/f883ab8f0daad69f47efdf95f55a66b51a8b939c430dadce0611508d9e99/pytest_cov-6.3.0.tar.gz", hash = "sha256:35c580e7800f87ce892e687461166e1ac2bcb8fb9e13aea79032518d6e503ff2", size = 70398, upload-time = "2025-09-06T15:40:14.361Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/80/b4/bb7263e12aade3842b938bc5c6958cae79c5ee18992f9b9349019579da0f/pytest_cov-6.3.0-py3-none-any.whl", hash = "sha256:440db28156d2468cafc0415b4f8e50856a0d11faefa38f30906048fe490f1749", size = 25115, upload-time = "2025-09-06T15:40:12.44Z" },
+]
+
 [[package]]
 name = "python-dateutil"
 version = "2.9.0.post0"
@@ -1153,6 +1220,15 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/45/58/38b5afbc1a800eeea951b9285d3912613f2603bdf897a4ab0f4bd7f405fc/python_multipart-0.0.20-py3-none-any.whl", hash = "sha256:8a62d3a8335e06589fe01f2a3e178cdcc632f3fbe0d492ad9ee0ec35aab1f104", size = 24546, upload-time = "2024-12-16T19:45:44.423Z" },
 ]
 
+[[package]]
+name = "pytokens"
+version = "0.1.10"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/30/5f/e959a442435e24f6fb5a01aec6c657079ceaca1b3baf18561c3728d681da/pytokens-0.1.10.tar.gz", hash = "sha256:c9a4bfa0be1d26aebce03e6884ba454e842f186a59ea43a6d3b25af58223c044", size = 12171, upload-time = "2025-02-19T14:51:22.001Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/60/e5/63bed382f6a7a5ba70e7e132b8b7b8abbcf4888ffa6be4877698dcfbed7d/pytokens-0.1.10-py3-none-any.whl", hash = "sha256:db7b72284e480e69fb085d9f251f66b3d2df8b7166059261258ff35f50fb711b", size = 12046, upload-time = "2025-02-19T14:51:18.694Z" },
+]
+
 [[package]]
 name = "pyyaml"
 version = "6.0.2"
diff --git a/docs/database/erd.md b/docs/database/erd.md
new file mode 100644
index 0000000000..649c5b86e4
--- /dev/null
+++ b/docs/database/erd.md
@@ -0,0 +1,193 @@
+# Database Entity Relationship Diagram (ERD)
+
+This document contains the automatically generated Entity Relationship Diagram for the FastAPI Template database schema. The ERD is generated from SQLModel definitions and updated automatically via git pre-commit hooks.
+
+## Overview
+
+The ERD below shows the current database schema with all tables, fields, relationships, and constraints. This diagram is automatically maintained and reflects the actual SQLModel definitions in the codebase.
+
+## Generated ERD
+
+```mermaid
+%% This diagram is automatically generated from SQLModel definitions
+%% Last updated: 2024-12-19
+%% Generated by: ERD Generator v1.0
+
+erDiagram
+
+USER {
+    uuid id PK
+    string hashed_password
+}
+
+ITEM {
+    uuid id PK
+    uuid owner_id FK NOT NULL
+}
+
+USER ||--o{ ITEM : items
+```
+
+## Schema Details
+
+### Tables
+
+#### USER
+- **Purpose**: Stores user account information
+- **Primary Key**: `id` (UUID)
+- **Fields**:
+  - `id`: Primary key (UUID, auto-generated)
+  - `hashed_password`: User's hashed password (string)
+
+#### ITEM
+- **Purpose**: Stores user-owned items
+- **Primary Key**: `id` (UUID)
+- **Foreign Keys**: 
+  - `owner_id` → `USER.id`
+- **Fields**:
+  - `id`: Primary key (UUID, auto-generated)
+  - `owner_id`: Foreign key to USER table (UUID, required)
+
+### Relationships
+
+#### USER → ITEM (One-to-Many)
+- **Type**: One-to-Many
+- **Description**: A user can own multiple items
+- **Implementation**: Foreign key `owner_id` in ITEM table
+- **Cascade**: Not specified (default behavior)
+
+## How This ERD is Maintained
+
+### Automatic Updates
+This ERD diagram is automatically updated whenever:
+- SQLModel definitions are modified in `backend/app/models.py`
+- New models are added or removed
+- Relationships between models change
+- Field definitions are updated
+
+### Update Mechanism
+The ERD is updated via a git pre-commit hook that:
+1. Detects changes to SQLModel files
+2. Regenerates the ERD from current model definitions
+3. Updates this documentation file
+4. Validates the generated ERD syntax
+
+### Manual Generation
+You can manually regenerate the ERD using:
+
+```bash
+# Generate ERD from current models
+python -m backend.scripts.generate_erd
+
+# Generate with validation
+python -m backend.scripts.generate_erd --validate --verbose
+
+# Generate to custom location
+python -m backend.scripts.generate_erd --output-path custom/erd.mmd
+```
+
+## Validation
+
+The ERD generation process includes validation to ensure:
+- All SQLModel classes with `table=True` are included
+- Primary keys are properly defined
+- Foreign key relationships are valid
+- Generated Mermaid syntax is correct
+- All entities have at least one field
+
+### Validation Checks
+- **Model Validation**: Ensures all models have required fields and valid relationships
+- **Syntax Validation**: Validates generated Mermaid ERD syntax
+- **Relationship Validation**: Ensures all relationships reference valid entities
+- **Constraint Validation**: Verifies database constraints are properly represented
+
+## Performance
+
+The ERD generation system is designed to handle:
+- **Small schemas** (< 5 tables): < 1 second
+- **Medium schemas** (5-10 tables): < 5 seconds  
+- **Large schemas** (10-20 tables): < 30 seconds
+- **Very large schemas** (20+ tables): Scales linearly
+
+## Troubleshooting
+
+### Common Issues
+
+#### ERD Not Updating
+- **Cause**: Pre-commit hook not installed or not running
+- **Solution**: Run `pre-commit install` and ensure hooks are enabled
+
+#### Invalid ERD Syntax
+- **Cause**: Malformed SQLModel definitions or relationship issues
+- **Solution**: Run `python -m backend.scripts.generate_erd --validate` to identify issues
+
+#### Missing Tables
+- **Cause**: SQLModel class missing `table=True` parameter
+- **Solution**: Ensure all database models have `table=True` in their class definition
+
+#### Relationship Issues
+- **Cause**: Incorrect `back_populates` or foreign key definitions
+- **Solution**: Verify relationship definitions match between related models
+
+### Getting Help
+
+If you encounter issues with the ERD generation:
+
+1. **Check validation output**:
+   ```bash
+   python -m backend.scripts.generate_erd --validate --verbose
+   ```
+
+2. **Review model definitions** in `backend/app/models.py`
+
+3. **Check pre-commit hook status**:
+   ```bash
+   pre-commit run erd-generation --verbose
+   ```
+
+4. **Regenerate from scratch**:
+   ```bash
+   rm docs/database/erd.mmd
+   python -m backend.scripts.generate_erd
+   ```
+
+## Technical Details
+
+### Generation Process
+1. **Model Discovery**: Scan for SQLModel classes in specified paths
+2. **Metadata Extraction**: Parse SQLModel definitions to extract schema information
+3. **Relationship Analysis**: Detect and analyze relationships between models
+4. **ERD Generation**: Create Mermaid ERD syntax from extracted metadata
+5. **Validation**: Validate generated ERD for syntax and semantic correctness
+6. **Output**: Write ERD to documentation file
+
+### Bidirectional Relationship Handling
+The ERD generator intelligently handles bidirectional relationships by:
+- Detecting relationships with `back_populates` parameters
+- Showing only the one-to-many direction to reduce visual clutter
+- Displaying foreign key fields to indicate reverse relationships
+- Avoiding redundant relationship lines
+
+### File Formats
+- **Input**: SQLModel Python classes in `backend/app/models.py`
+- **Output**: Mermaid ERD syntax in `docs/database/erd.mmd`
+- **Documentation**: Markdown with embedded Mermaid in `docs/database/erd.md`
+
+## Integration
+
+This ERD system integrates with:
+- **Git Workflow**: Automatic updates via pre-commit hooks
+- **Documentation**: Part of project documentation standards
+- **CI/CD**: Can be included in build and deployment pipelines
+- **Development**: Provides real-time schema visualization
+
+## Related Documentation
+
+- [Database Models](../backend/app/models.py) - SQLModel definitions
+- [ERD Generator](../backend/app/erd_generator.py) - Generation logic
+- [Quickstart Guide](../../specs/001-as-a-first/quickstart.md) - Usage instructions
+- [Project Constitution](../../.specify/memory/constitution.md) - Documentation standards
+
+---
+
+*This documentation is automatically maintained. Do not edit manually - changes will be overwritten.*
diff --git a/docs/database/erd.mmd b/docs/database/erd.mmd
new file mode 100644
index 0000000000..99f5e7e9ad
--- /dev/null
+++ b/docs/database/erd.mmd
@@ -0,0 +1,22 @@
+%% Database ERD Diagram
+%% Generated: 2025-10-03T15:16:11.880836
+%% Version: Unknown
+%% Entities: 2
+%% Relationships: 1
+%% Status: invalid
+
+%% This diagram is automatically generated from SQLModel definitions
+
+erDiagram
+
+USER {
+    uuid id PK
+    string hashed_password
+}
+
+ITEM {
+    uuid id PK
+    uuid owner_id FK NOT NULL
+}
+
+USER ||--o{ ITEM : items
\ No newline at end of file
diff --git a/specs/001-as-a-first/contracts/cli-interface.md b/specs/001-as-a-first/contracts/cli-interface.md
new file mode 100644
index 0000000000..ad9254d5ca
--- /dev/null
+++ b/specs/001-as-a-first/contracts/cli-interface.md
@@ -0,0 +1,70 @@
+# Contract: CLI Interface for ERD Generation
+
+## Command: `generate-erd`
+
+### Purpose
+Command-line interface for manually generating ERD diagrams from SQLModel definitions.
+
+### Usage
+```bash
+python -m backend.scripts.generate_erd [options]
+```
+
+### Options
+- `--models-path PATH`: Path to SQLModel definitions (default: `backend/app/models.py`)
+- `--output-path PATH`: Path for generated ERD documentation (default: `docs/database/erd.md`)
+- `--validate`: Run validation checks on generated ERD
+- `--verbose`: Enable verbose output
+- `--help`: Show help message
+
+### Input Requirements
+- Valid SQLModel definitions at specified path
+- Writable output directory
+- Python environment with required dependencies
+
+### Output Specification
+- Generated ERD documentation in Markdown format
+- Mermaid ERD syntax embedded in code blocks
+- Validation report if `--validate` flag used
+- Exit code: 0 for success, non-zero for errors
+
+### Error Conditions
+- Invalid SQLModel syntax → Exit code 1, error message to stderr
+- Missing models file → Exit code 2, error message to stderr
+- Unwritable output path → Exit code 3, error message to stderr
+- Validation failures → Exit code 4, validation report to stdout
+
+### Success Criteria
+- ERD diagram generated successfully
+- Output file created and writable
+- Mermaid syntax valid and renderable
+- All validation checks pass (if requested)
+
+## Command: `validate-erd`
+
+### Purpose
+Validate existing ERD diagram against current SQLModel definitions.
+
+### Usage
+```bash
+python -m backend.scripts.generate_erd --validate
+```
+
+### Input Requirements
+- Existing ERD documentation file
+- Current SQLModel definitions
+- Python environment with required dependencies
+
+### Output Specification
+- Validation report to stdout
+- Exit code: 0 for valid, non-zero for invalid
+
+### Error Conditions
+- Missing ERD file → Exit code 1
+- Invalid ERD syntax → Exit code 2
+- Mismatch with models → Exit code 3
+
+### Success Criteria
+- ERD syntax valid
+- ERD matches current model definitions
+- All entities and relationships correctly represented
diff --git a/specs/001-as-a-first/contracts/pre-commit-hook.md b/specs/001-as-a-first/contracts/pre-commit-hook.md
new file mode 100644
index 0000000000..d71b1352d6
--- /dev/null
+++ b/specs/001-as-a-first/contracts/pre-commit-hook.md
@@ -0,0 +1,75 @@
+# Contract: Pre-commit Hook Integration
+
+## Hook: `erd-generation`
+
+### Purpose
+Automatically generate and validate ERD diagrams before each commit to ensure documentation stays current.
+
+### Trigger Conditions
+- Any changes to SQLModel definition files
+- Any changes to ERD generation configuration
+- Manual trigger via `pre-commit run erd-generation`
+
+### Input Requirements
+- Modified files list from git
+- Current SQLModel definitions
+- ERD generation configuration
+- Python environment with required dependencies
+
+### Processing Logic
+1. **File Detection**: Check if any SQLModel files were modified
+2. **Model Parsing**: Parse current SQLModel definitions
+3. **ERD Generation**: Generate updated ERD diagram
+4. **Validation**: Validate generated ERD against models
+5. **Documentation Update**: Update ERD documentation file
+6. **Git Integration**: Stage updated documentation if changed
+
+### Output Specification
+- Updated ERD documentation file
+- Validation report to stdout
+- Exit code: 0 for success, non-zero for failure
+
+### Error Handling
+- **Parse Errors**: Fail commit with clear error message
+- **Validation Errors**: Fail commit with validation report
+- **Generation Errors**: Fail commit with generation error details
+- **File Errors**: Fail commit with file operation error
+
+### Success Criteria
+- ERD diagram generated successfully
+- Documentation file updated
+- All validation checks pass
+- Changes staged for commit
+
+### Configuration
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: erd-generation
+        name: Generate ERD Diagram
+        entry: python -m backend.scripts.generate_erd --pre-commit
+        language: system
+        files: ^backend/app/models\.py$
+        pass_filenames: false
+        always_run: false
+```
+
+### Integration Requirements
+- Pre-commit framework installed and configured
+- ERD generation script available in PATH
+- Write access to documentation directory
+- Git repository with proper permissions
+
+### Performance Considerations
+- Hook should complete within 30 seconds
+- Only run when SQLModel files are modified
+- Cache model metadata when possible
+- Fail fast on validation errors
+
+### Rollback Behavior
+- Failed commits leave repository in clean state
+- No partial ERD updates committed
+- Clear error messages for debugging
+- Manual override available for emergency commits
diff --git a/specs/001-as-a-first/contracts/validation-contract.md b/specs/001-as-a-first/contracts/validation-contract.md
new file mode 100644
index 0000000000..a38d318ff4
--- /dev/null
+++ b/specs/001-as-a-first/contracts/validation-contract.md
@@ -0,0 +1,102 @@
+# Contract: ERD Validation System
+
+## Validation: `erd-accuracy`
+
+### Purpose
+Validate that generated ERD diagrams accurately represent current SQLModel definitions.
+
+### Validation Scope
+- Entity completeness and accuracy
+- Field definitions and types
+- Relationship cardinality and constraints
+- Primary key definitions
+- Foreign key relationships
+- Mermaid syntax validity
+
+### Input Requirements
+- Current SQLModel definitions
+- Generated ERD diagram (Mermaid syntax)
+- Validation configuration
+- Python environment with required dependencies
+
+### Validation Rules
+
+#### Entity Validation
+- All SQLModel classes with `table=True` must be represented in ERD
+- Entity names must match table names exactly
+- No extra entities in ERD that don't exist in models
+- No missing entities in ERD that exist in models
+
+#### Field Validation
+- All model fields must be represented in ERD
+- Field types must be accurately represented
+- Nullable constraints must be correctly shown
+- Default values must be preserved
+- Field names must match exactly
+
+#### Relationship Validation
+- All foreign key relationships must be represented
+- Relationship cardinality must be correct
+- Foreign key field names must match
+- Constraint types (CASCADE, SET NULL) must be preserved
+- No orphaned relationships in ERD
+
+#### Syntax Validation
+- Mermaid ERD syntax must be valid
+- Diagram must be renderable by Mermaid
+- No syntax errors or warnings
+- Proper formatting and indentation
+
+### Output Specification
+- Validation report with detailed results
+- Error count and severity levels
+- Specific validation failures with line numbers
+- Success/failure status
+- Exit code: 0 for valid, non-zero for invalid
+
+### Error Severity Levels
+- **Critical**: Missing entities, invalid syntax, broken relationships
+- **Warning**: Type mismatches, constraint differences
+- **Info**: Formatting issues, optimization suggestions
+
+### Validation Modes
+- **Strict**: All validations must pass (default)
+- **Permissive**: Allow warnings, fail only on critical errors
+- **Report**: Generate report without failing validation
+
+### Success Criteria
+- All entities correctly represented
+- All fields accurately defined
+- All relationships properly shown
+- Valid Mermaid syntax
+- No critical or warning errors
+
+### Failure Handling
+- Detailed error messages for each validation failure
+- Line number references for syntax errors
+- Suggestions for fixing validation issues
+- Clear indication of what needs to be corrected
+
+### Performance Requirements
+- Validation must complete within 10 seconds
+- Memory usage should be reasonable for typical schemas
+- No external dependencies for basic validation
+- Caching of validation results when possible
+
+### Integration Points
+- CLI interface validation mode
+- Pre-commit hook validation
+- CI/CD pipeline validation
+- Manual validation workflow
+
+### Configuration Options
+```python
+validation_config = {
+    "strict_mode": True,
+    "check_syntax": True,
+    "validate_relationships": True,
+    "validate_constraints": True,
+    "max_errors": 10,
+    "timeout_seconds": 30
+}
+```
diff --git a/specs/001-as-a-first/data-model.md b/specs/001-as-a-first/data-model.md
new file mode 100644
index 0000000000..b75a2745cd
--- /dev/null
+++ b/specs/001-as-a-first/data-model.md
@@ -0,0 +1,123 @@
+# Data Model: Mermaid ERD Diagram Documentation
+
+## Core Entities
+
+### ERD Generator
+**Purpose**: Main entity responsible for generating Mermaid ERD diagrams from SQLModel definitions
+
+**Attributes**:
+- `models_path`: Path to SQLModel definitions (default: `backend/app/models.py`)
+- `output_path`: Path for generated ERD documentation (default: `docs/database/erd.md`)
+- `mermaid_syntax`: Mermaid ERD syntax configuration
+- `validation_rules`: Rules for ERD validation and error checking
+
+**Relationships**:
+- Generates: ERD Output
+- Validates: Model Metadata
+- Processes: Database Models
+
+### Model Metadata
+**Purpose**: Extracted metadata from SQLModel classes for ERD generation
+
+**Attributes**:
+- `class_name`: Name of the SQLModel class
+- `table_name`: Database table name (inferred from class)
+- `fields`: List of field metadata objects
+- `relationships`: List of relationship metadata objects
+- `constraints`: List of constraint metadata objects
+- `primary_key`: Primary key field information
+
+**Relationships**:
+- Extracted from: Database Models
+- Used by: ERD Generator
+
+### ERD Output
+**Purpose**: Generated Mermaid ERD diagram structure
+
+**Attributes**:
+- `mermaid_code`: Raw Mermaid syntax string
+- `entities`: List of entity definitions
+- `relationships`: List of relationship definitions
+- `metadata`: Generation metadata (timestamp, version, etc.)
+- `validation_status`: Status of ERD validation
+
+**Relationships**:
+- Generated by: ERD Generator
+- Contains: Entity Definitions, Relationship Definitions
+
+### Entity Definition
+**Purpose**: Individual entity (table) definition in ERD
+
+**Attributes**:
+- `name`: Entity/table name
+- `fields`: List of field definitions
+- `primary_key`: Primary key field
+- `constraints`: List of constraints (unique, not null, etc.)
+
+**Relationships**:
+- Part of: ERD Output
+- Has: Field Definitions
+
+### Field Definition
+**Purpose**: Individual field definition within an entity
+
+**Attributes**:
+- `name`: Field name
+- `type`: Field data type
+- `nullable`: Whether field allows null values
+- `unique`: Whether field has unique constraint
+- `default`: Default value if any
+- `foreign_key`: Foreign key constraint if any
+
+**Relationships**:
+- Belongs to: Entity Definition
+
+### Relationship Definition
+**Purpose**: Relationship between entities in ERD
+
+**Attributes**:
+- `from_entity`: Source entity name
+- `to_entity`: Target entity name
+- `cardinality`: Relationship cardinality (1:1, 1:N, N:M)
+- `foreign_key_field`: Field that implements the relationship
+- `constraint_type`: Type of constraint (CASCADE, SET NULL, etc.)
+
+**Relationships**:
+- Part of: ERD Output
+- Connects: Entity Definitions
+
+## State Transitions
+
+### ERD Generation Workflow
+1. **Initialization**: ERD Generator loads configuration
+2. **Model Discovery**: Scan for SQLModel classes in specified path
+3. **Metadata Extraction**: Parse SQLModel definitions to extract metadata
+4. **Validation**: Validate model metadata for ERD generation
+5. **Diagram Generation**: Create Mermaid ERD syntax from metadata
+6. **Output Creation**: Generate ERD Output with Mermaid code
+7. **Documentation Update**: Write ERD to documentation file
+
+### Error States
+- **Parse Error**: Invalid SQLModel syntax detected
+- **Validation Error**: Model metadata fails validation rules
+- **Generation Error**: ERD generation fails due to model issues
+- **Output Error**: File writing or documentation update fails
+
+## Validation Rules
+
+### Model Metadata Validation
+- All SQLModel classes must have `table=True` for ERD inclusion
+- Primary keys must be properly defined
+- Foreign key relationships must reference valid entities
+- Field types must be supported by Mermaid ERD syntax
+
+### ERD Output Validation
+- Generated Mermaid syntax must be valid
+- All entities must have at least one field
+- Relationships must reference existing entities
+- Diagram must be renderable by Mermaid
+
+### Documentation Integration Validation
+- Output file must be writable
+- Generated content must follow project documentation standards
+- ERD must be properly formatted for Markdown rendering
diff --git a/specs/001-as-a-first/plan.md b/specs/001-as-a-first/plan.md
new file mode 100644
index 0000000000..9634e10543
--- /dev/null
+++ b/specs/001-as-a-first/plan.md
@@ -0,0 +1,205 @@
+# Implementation Plan: Mermaid ERD Diagram Documentation
+
+**Branch**: `001-as-a-first` | **Date**: 2024-12-19 | **Spec**: `/specs/001-as-a-first/spec.md`
+**Input**: Feature specification from `/specs/001-as-a-first/spec.md`
+
+## Execution Flow (/plan command scope)
+```
+1. Load feature spec from Input path
+   → If not found: ERROR "No feature spec at {path}"
+2. Fill Technical Context (scan for NEEDS CLARIFICATION)
+   → Detect Project Type from file system structure or context (web=frontend+backend, mobile=app+api)
+   → Set Structure Decision based on project type
+3. Fill the Constitution Check section based on the content of the constitution document.
+4. Evaluate Constitution Check section below
+   → If violations exist: Document in Complexity Tracking
+   → If no justification possible: ERROR "Simplify approach first"
+   → Update Progress Tracking: Initial Constitution Check
+5. Execute Phase 0 → research.md
+   → If NEEDS CLARIFICATION remain: ERROR "Resolve unknowns"
+6. Execute Phase 1 → contracts, data-model.md, quickstart.md, agent-specific template file (e.g., `CLAUDE.md` for Claude Code, `.github/copilot-instructions.md` for GitHub Copilot, `GEMINI.md` for Gemini CLI, `QWEN.md` for Qwen Code or `AGENTS.md` for opencode).
+7. Re-evaluate Constitution Check section
+   → If new violations: Refactor design, return to Phase 1
+   → Update Progress Tracking: Post-Design Constitution Check
+8. Plan Phase 2 → Describe task generation approach (DO NOT create tasks.md)
+9. STOP - Ready for /tasks command
+```
+
+**IMPORTANT**: The /plan command STOPS at step 7. Phases 2-4 are executed by other commands:
+- Phase 2: /tasks command creates tasks.md
+- Phase 3-4: Implementation execution (manual or via tools)
+
+## Summary
+Generate Mermaid ERD diagrams from SQLModel database models with automatic updates via git pre-commit hooks, integrated into project documentation standards and constitution requirements.
+
+## Technical Context
+**Language/Version**: Python 3.11+  
+**Primary Dependencies**: SQLModel, Mermaid, Git hooks, pre-commit framework  
+**Storage**: File-based ERD output (Markdown/Mermaid format)  
+**Testing**: pytest for unit tests, pre-commit hooks for integration  
+**Target Platform**: Cross-platform (Linux/macOS/Windows)  
+**Project Type**: web (FastAPI + React full-stack template)  
+**Performance Goals**: Reasonable generation time for typical database schemas  
+**Constraints**: Must work in Docker environment, fail-fast error handling  
+**Scale/Scope**: Single project template with extensible model support
+
+## Constitution Check
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+**Full-Stack Integration**: ✅ YES - Requires backend model parsing, documentation updates, and git workflow integration
+**Test-Driven Development**: ✅ YES - Test scenarios defined for ERD generation, validation, and error handling
+**Auto-Generated Client**: ❌ NO - This is documentation generation, not API client generation
+**Docker-First**: ✅ YES - ERD generation must work in containerized environment
+**Security by Default**: ✅ YES - Input validation for model parsing, secure file handling
+
+## Project Structure
+
+### Documentation (this feature)
+```
+specs/001-as-a-first/
+├── plan.md              # This file (/plan command output)
+├── research.md          # Phase 0 output (/plan command)
+├── data-model.md        # Phase 1 output (/plan command)
+├── quickstart.md        # Phase 1 output (/plan command)
+├── contracts/           # Phase 1 output (/plan command)
+└── tasks.md             # Phase 2 output (/tasks command - NOT created by /plan)
+```
+
+### Source Code (repository root)
+```
+backend/
+├── app/
+│   ├── models.py        # Existing SQLModel definitions
+│   └── erd_generator.py # New ERD generation module
+├── scripts/
+│   └── generate_erd.py  # CLI script for ERD generation
+└── tests/
+    ├── unit/
+    │   └── test_erd_generator.py
+    └── integration/
+        └── test_erd_workflow.py
+
+.git/
+└── hooks/
+    └── pre-commit       # Updated to include ERD generation
+
+docs/
+└── database/
+    └── erd.md          # Generated ERD documentation
+
+.specify/
+├── memory/
+│   └── constitution.md  # Updated with ERD requirements
+└── templates/
+    ├── plan-template.md # Updated with ERD checks
+    └── tasks-template.md # Updated with ERD maintenance
+```
+
+**Structure Decision**: Web application structure with backend focus, documentation integration, and git workflow enhancement
+
+## Phase 0: Outline & Research
+1. **Extract unknowns from Technical Context** above:
+   - Mermaid ERD syntax and best practices for SQLModel relationships
+   - Git pre-commit hook integration patterns
+   - SQLModel introspection and parsing techniques
+   - Documentation integration approaches
+
+2. **Generate and dispatch research agents**:
+   ```
+   Task: "Research Mermaid ERD syntax for SQLModel relationships and foreign keys"
+   Task: "Find best practices for git pre-commit hooks with Python projects"
+   Task: "Research SQLModel introspection patterns for automatic schema extraction"
+   Task: "Find documentation integration patterns for auto-generated diagrams"
+   ```
+
+3. **Consolidate findings** in `research.md` using format:
+   - Decision: [what was chosen]
+   - Rationale: [why chosen]
+   - Alternatives considered: [what else evaluated]
+
+**Output**: research.md with all NEEDS CLARIFICATION resolved
+
+## Phase 1: Design & Contracts
+*Prerequisites: research.md complete*
+
+1. **Extract entities from feature spec** → `data-model.md`:
+   - ERD Generator entity with parsing capabilities
+   - Model Metadata entity for SQLModel introspection
+   - ERD Output entity for Mermaid diagram structure
+
+2. **Generate API contracts** from functional requirements:
+   - CLI interface for manual ERD generation
+   - Pre-commit hook integration contract
+   - Validation contract for ERD accuracy
+
+3. **Generate contract tests** from contracts:
+   - CLI command tests
+   - Pre-commit hook integration tests
+   - ERD validation tests
+
+4. **Extract test scenarios** from user stories:
+   - ERD generation workflow test
+   - Automatic update workflow test
+   - Error handling workflow test
+
+5. **Update agent file incrementally** (O(1) operation):
+   - Run `.specify/scripts/bash/update-agent-context.sh cursor`
+     **IMPORTANT**: Execute it exactly as specified above. Do not add or remove any arguments.
+   - Add ERD generation context to agent guidance
+
+**Output**: data-model.md, /contracts/*, failing tests, quickstart.md, agent-specific file
+
+## Phase 2: Task Planning Approach
+*This section describes what the /tasks command will do - DO NOT execute during /plan*
+
+**Task Generation Strategy**:
+- Load `.specify/templates/tasks-template.md` as base
+- Generate tasks from Phase 1 design docs (contracts, data model, quickstart)
+- ERD Generator module → implementation task [P]
+- CLI interface → implementation task [P]
+- Pre-commit hook → integration task
+- Documentation updates → documentation task [P]
+- Constitution updates → governance task [P]
+
+**Ordering Strategy**:
+- TDD order: Tests before implementation 
+- Dependency order: Core generator → CLI → Integration → Documentation
+- Mark [P] for parallel execution (independent files)
+
+**Estimated Output**: 15-20 numbered, ordered tasks in tasks.md
+
+**IMPORTANT**: This phase is executed by the /tasks command, NOT by /plan
+
+## Phase 3+: Future Implementation
+*These phases are beyond the scope of the /plan command*
+
+**Phase 3**: Task execution (/tasks command creates tasks.md)  
+**Phase 4**: Implementation (execute tasks.md following constitutional principles)  
+**Phase 5**: Validation (run tests, execute quickstart.md, performance validation)
+
+## Complexity Tracking
+*Fill ONLY if Constitution Check has violations that must be justified*
+
+| Violation | Why Needed | Simpler Alternative Rejected Because |
+|-----------|------------|-------------------------------------|
+| Auto-Generated Client: NO | This feature generates documentation, not API clients | N/A - not applicable to documentation generation |
+
+## Progress Tracking
+*This checklist is updated during execution flow*
+
+**Phase Status**:
+- [x] Phase 0: Research complete (/plan command)
+- [x] Phase 1: Design complete (/plan command)
+- [x] Phase 2: Task planning complete (/plan command - describe approach only)
+- [ ] Phase 3: Tasks generated (/tasks command)
+- [ ] Phase 4: Implementation complete
+- [ ] Phase 5: Validation passed
+
+**Gate Status**:
+- [x] Initial Constitution Check: PASS
+- [x] Post-Design Constitution Check: PASS
+- [x] All NEEDS CLARIFICATION resolved
+- [x] Complexity deviations documented
+
+---
+*Based on Constitution v1.0.0 - See `/memory/constitution.md`*
\ No newline at end of file
diff --git a/specs/001-as-a-first/quickstart.md b/specs/001-as-a-first/quickstart.md
new file mode 100644
index 0000000000..b35ad391e4
--- /dev/null
+++ b/specs/001-as-a-first/quickstart.md
@@ -0,0 +1,166 @@
+# Quickstart: Mermaid ERD Diagram Documentation
+
+## Overview
+This quickstart guide demonstrates how to use the ERD generation system to create and maintain Mermaid Entity Relationship Diagrams for the FastAPI Template project.
+
+## Prerequisites
+- Python 3.11+ environment
+- FastAPI Template project with SQLModel definitions
+- Pre-commit framework installed (for automatic updates)
+
+## Basic Usage
+
+### 1. Generate ERD Diagram
+```bash
+# Generate ERD from current models
+python -m backend.scripts.generate_erd
+
+# Generate with custom paths
+python -m backend.scripts.generate_erd --models-path backend/app/models.py --output-path docs/database/erd.md
+
+# Generate with validation
+python -m backend.scripts.generate_erd --validate --verbose
+```
+
+### 2. View Generated ERD
+The ERD diagram will be generated at `docs/database/erd.md` and can be viewed in any Markdown renderer that supports Mermaid diagrams.
+
+### 3. Validate ERD Accuracy
+```bash
+# Validate existing ERD against current models
+python -m backend.scripts.generate_erd --validate
+
+# Validate with detailed report
+python -m backend.scripts.generate_erd --validate --verbose
+```
+
+## Automatic Updates
+
+### Pre-commit Hook Setup
+The ERD diagram will be automatically updated when you commit changes to SQLModel definitions:
+
+```bash
+# Install pre-commit hooks (if not already done)
+pre-commit install
+
+# Test the hook
+pre-commit run erd-generation
+
+# Commit changes (hook runs automatically)
+git add backend/app/models.py
+git commit -m "Add new User model"
+```
+
+### Manual Hook Execution
+```bash
+# Run ERD generation hook manually
+pre-commit run erd-generation
+
+# Run all hooks including ERD generation
+pre-commit run --all-files
+```
+
+## Workflow Examples
+
+### Adding a New Model
+1. **Create SQLModel class** in `backend/app/models.py`:
+   ```python
+   class Product(SQLModel, table=True):
+       id: uuid.UUID = Field(default_factory=uuid.uuid4, primary_key=True)
+       name: str = Field(max_length=255)
+       price: decimal.Decimal = Field(max_digits=10, decimal_places=2)
+       category_id: uuid.UUID = Field(foreign_key="category.id")
+       category: Category | None = Relationship(back_populates="products")
+   ```
+
+2. **Commit changes** (ERD updates automatically):
+   ```bash
+   git add backend/app/models.py
+   git commit -m "Add Product model"
+   ```
+
+3. **Verify ERD update**:
+   ```bash
+   # Check if ERD was updated
+   git diff HEAD~1 docs/database/erd.md
+   
+   # Validate ERD accuracy
+   python -m backend.scripts.generate_erd --validate
+   ```
+
+### Modifying Existing Model
+1. **Update SQLModel definition** in `backend/app/models.py`
+2. **Commit changes** (ERD updates automatically)
+3. **Validate changes** with `--validate` flag
+
+### Troubleshooting
+```bash
+# Check ERD generation status
+python -m backend.scripts.generate_erd --verbose
+
+# Validate ERD syntax
+python -m backend.scripts.generate_erd --validate
+
+# Regenerate ERD from scratch
+rm docs/database/erd.md
+python -m backend.scripts.generate_erd
+```
+
+## Expected Output
+
+### Generated ERD Structure
+The generated ERD will include:
+- All SQLModel classes with `table=True`
+- Field definitions with types and constraints
+- Relationship lines showing foreign keys
+- Cardinality indicators (1:1, 1:N, N:M)
+- Primary key indicators
+
+### Example ERD Output
+```mermaid
+erDiagram
+    USER {
+        uuid id PK
+        string email UK
+        boolean is_active
+        boolean is_superuser
+        string full_name
+        string hashed_password
+    }
+    
+    ITEM {
+        uuid id PK
+        string title
+        string description
+        uuid owner_id FK
+    }
+    
+    USER ||--o{ ITEM : owns
+```
+
+## Integration with Development Workflow
+
+### Constitution Compliance
+- ERD generation follows Full-Stack Integration principle
+- Documentation updates follow Documentation Standards
+- Pre-commit hooks follow Code Quality Standards
+- Error handling follows Security by Default principle
+
+### Template Updates
+- Constitution updated with ERD documentation requirements
+- Plan template includes ERD generation checks
+- Task template includes ERD maintenance tasks
+
+## Support and Troubleshooting
+
+### Common Issues
+- **Parse Errors**: Check SQLModel syntax and imports
+- **Validation Failures**: Verify model definitions and relationships
+- **Hook Failures**: Check pre-commit configuration and permissions
+- **Generation Errors**: Validate Python environment and dependencies
+
+### Getting Help
+- Check validation output for specific error messages
+- Review ERD generation logs with `--verbose` flag
+- Verify pre-commit hook configuration
+- Consult project documentation for model definitions
diff --git a/specs/001-as-a-first/research.md b/specs/001-as-a-first/research.md
new file mode 100644
index 0000000000..fd6ccc4cca
--- /dev/null
+++ b/specs/001-as-a-first/research.md
@@ -0,0 +1,86 @@
+# Research: Mermaid ERD Diagram Documentation
+
+## Mermaid ERD Syntax for SQLModel Relationships
+
+**Decision**: Use Mermaid ERD syntax with explicit relationship notation
+**Rationale**: Mermaid provides standardized ERD syntax that supports:
+- Entity definitions with attributes
+- Relationship cardinality (one-to-one, one-to-many, many-to-many)
+- Foreign key constraints
+- Primary key identification
+- Clear visual representation
+
+**Alternatives considered**:
+- PlantUML ERD: More complex syntax, requires additional dependencies
+- Draw.io XML: Not text-based, harder to version control
+- Custom diagram format: Would require custom rendering tools
+
+## Git Pre-commit Hook Integration Patterns
+
+**Decision**: Use pre-commit framework with custom hook for ERD generation
+**Rationale**: Pre-commit framework provides:
+- Standardized hook management
+- Integration with existing project workflow
+- Support for multiple hook types
+- Easy installation and configuration
+
+**Alternatives considered**:
+- Native git hooks: Harder to manage and distribute
+- CI/CD only: Doesn't catch issues before commit
+- Manual process: Prone to human error and inconsistency
+
+## SQLModel Introspection and Parsing Techniques
+
+**Decision**: Use Python AST parsing and SQLModel metadata for model extraction
+**Rationale**: AST parsing provides:
+- Reliable model structure extraction
+- Access to field types and constraints
+- Relationship detection via SQLModel metadata
+- No runtime database dependency
+
+**Alternatives considered**:
+- Database introspection: Requires active database connection
+- Reflection-based parsing: Less reliable, runtime dependent
+- Manual model mapping: Prone to errors and maintenance issues
+
+## Documentation Integration Approaches
+
+**Decision**: Generate ERD as Mermaid code blocks in Markdown documentation
+**Rationale**: Markdown with Mermaid provides:
+- Version control friendly format
+- Easy integration with existing documentation
+- Support for multiple diagram types
+- Standard rendering in most documentation platforms
+
+**Alternatives considered**:
+- Separate image files: Harder to maintain, not version control friendly
+- Embedded HTML: More complex, platform dependent
+- External documentation tools: Additional dependencies and complexity
+
+## Error Handling and Validation
+
+**Decision**: Implement fail-fast validation with clear error messages
+**Rationale**: Fail-fast approach ensures:
+- Immediate feedback on model issues
+- Clear error messages for debugging
+- Prevention of invalid ERD generation
+- Integration with existing project error handling patterns
+
+**Alternatives considered**:
+- Graceful degradation: Could hide important model issues
+- Warning system: Adds complexity without clear benefit
+- Retry mechanisms: Not applicable to model parsing errors
+
+## Performance Considerations
+
+**Decision**: Generate ERD on-demand with reasonable performance expectations
+**Rationale**: On-demand generation provides:
+- Always up-to-date diagrams
+- No stale documentation issues
+- Reasonable performance for typical schemas
+- Integration with git workflow
+
+**Alternatives considered**:
+- Cached generation: Risk of stale diagrams
+- Background generation: Adds complexity
+- Manual generation only: Defeats automation purpose
diff --git a/specs/001-as-a-first/spec.md b/specs/001-as-a-first/spec.md
new file mode 100644
index 0000000000..e6f0aae3a6
--- /dev/null
+++ b/specs/001-as-a-first/spec.md
@@ -0,0 +1,132 @@
+# Feature Specification: Mermaid ERD Diagram Documentation
+
+**Feature Branch**: `001-as-a-first`  
+**Created**: 2024-12-19  
+**Status**: Draft  
+**Input**: User description: "As a first feature I want to generate a Mermaid ERD diagram as Documentation. I also want to add it to the spec kit constitution and approriate templates so that when we make changes to the any of the database @models.py we also update the ERD diagram."
+
+## Execution Flow (main)
+```
+1. Parse user description from Input
+   → If empty: ERROR "No feature description provided"
+2. Extract key concepts from description
+   → Identify: actors, actions, data, constraints
+3. For each unclear aspect:
+   → Mark with [NEEDS CLARIFICATION: specific question]
+4. Fill User Scenarios & Testing section
+   → If no clear user flow: ERROR "Cannot determine user scenarios"
+5. Generate Functional Requirements
+   → Each requirement must be testable
+   → Mark ambiguous requirements
+6. Identify Key Entities (if data involved)
+7. Run Review Checklist
+   → If any [NEEDS CLARIFICATION]: WARN "Spec has uncertainties"
+   → If implementation details found: ERROR "Remove tech details"
+8. Return: SUCCESS (spec ready for planning)
+```
+
+---
+
+## ⚡ Quick Guidelines
+- ✅ Focus on WHAT users need and WHY
+- ❌ Avoid HOW to implement (no tech stack, APIs, code structure)
+- 👥 Written for business stakeholders, not developers
+
+### Section Requirements
+- **Mandatory sections**: Must be completed for every feature
+- **Optional sections**: Include only when relevant to the feature
+- When a section doesn't apply, remove it entirely (don't leave as "N/A")
+
+### For AI Generation
+When creating this spec from a user prompt:
+1. **Mark all ambiguities**: Use [NEEDS CLARIFICATION: specific question] for any assumption you'd need to make
+2. **Don't guess**: If the prompt doesn't specify something (e.g., "login system" without auth method), mark it
+3. **Think like a tester**: Every vague requirement should fail the "testable and unambiguous" checklist item
+4. **Common underspecified areas**:
+   - User types and permissions
+   - Data retention/deletion policies  
+   - Performance targets and scale
+   - Error handling behaviors
+   - Integration requirements
+   - Security/compliance needs
+
+---
+
+## User Scenarios & Testing *(mandatory)*
+
+### Primary User Story
+As a developer working on the FastAPI Template project, I want to have an automatically generated Entity Relationship Diagram (ERD) that visualizes the database schema, so that I can quickly understand the data model and relationships between entities without manually examining the SQLModel definitions.
+
+### Acceptance Scenarios
+1. **Given** the database models are defined in `backend/app/models.py`, **When** I run the ERD generation process, **Then** I should receive a Mermaid ERD diagram showing all tables, their fields, data types, and relationships
+2. **Given** I modify any database model in `models.py`, **When** I commit my changes, **Then** the ERD diagram should be automatically updated to reflect the new schema
+3. **Given** the ERD diagram exists, **When** I view the project documentation, **Then** I should see the current ERD diagram displayed in a readable format
+4. **Given** I am following the project's development workflow, **When** I make database model changes, **Then** the constitution and templates should remind me to update the ERD documentation
+
+### Edge Cases
+- What happens when the ERD generation process encounters invalid or malformed model definitions?
+- How does the system handle circular relationships between database entities?
+- What occurs when model changes break the existing ERD generation process?
+
+## Requirements *(mandatory)*
+
+### Functional Requirements
+- **FR-001**: System MUST generate a Mermaid ERD diagram from all database models (including those that may expand beyond `backend/app/models.py`)
+- **FR-002**: System MUST display all database tables with their field names, data types, and constraints
+- **FR-003**: System MUST show relationships between tables including foreign keys and cardinality
+- **FR-004**: System MUST automatically update the ERD diagram when database models are modified via git pre-commit hook
+- **FR-005**: System MUST integrate ERD requirements into existing documentation principles in the project constitution
+- **FR-006**: System MUST update project templates to include ERD maintenance requirements
+- **FR-007**: System MUST validate ERD diagram accuracy by parsing SQLModel definitions and provide a manual validation checklist for developers
+- **FR-008**: System MUST fail fast and show clear error messages when ERD generation encounters invalid or malformed model definitions
+
+### Key Entities *(include if feature involves data)*
+- **Database Models**: SQLModel classes that represent database tables (User, Item, etc.)
+- **ERD Diagram**: Visual representation of database schema using Mermaid syntax
+- **Model Relationships**: Foreign key constraints and associations between tables
+- **Documentation**: Project documentation that includes the ERD diagram
+
+## Non-Functional Requirements
+- **NFR-001**: ERD generation MUST complete within 30 seconds for schemas with up to 20 tables and 100 fields
+
+## Clarifications
+
+### Session 2024-12-19
+- Q: When ERD generation fails, how should the system behave? → A: Fail fast - stop the process and show clear error message
+- Q: What are the acceptable performance targets for ERD generation? → A: Complete within 30 seconds for schemas with up to 20 tables and 100 fields
+- Q: How should the ERD diagram be automatically updated when database models are modified? → A: Git pre-commit hook that regenerates ERD before commits
+- Q: How should the system validate that the generated ERD diagram accurately represents the current database models? → A: Parse and validate against SQLModel definitions only + manual validation checklist for developers
+- Q: How should the ERD documentation requirements be integrated into the project constitution and templates? → A: Add ERD requirements to existing documentation principles
+
+---
+
+## Review & Acceptance Checklist
+*GATE: Automated checks run during main() execution*
+
+### Content Quality
+- [ ] No implementation details (languages, frameworks, APIs)
+- [ ] Focused on user value and business needs
+- [ ] Written for non-technical stakeholders
+- [ ] All mandatory sections completed
+
+### Requirement Completeness
+- [ ] No [NEEDS CLARIFICATION] markers remain
+- [ ] Requirements are testable and unambiguous  
+- [ ] Success criteria are measurable
+- [ ] Scope is clearly bounded
+- [ ] Dependencies and assumptions identified
+
+---
+
+## Execution Status
+*Updated by main() during processing*
+
+- [x] User description parsed
+- [x] Key concepts extracted
+- [x] Ambiguities marked
+- [x] User scenarios defined
+- [x] Requirements generated
+- [x] Entities identified
+- [ ] Review checklist passed
+
+---
\ No newline at end of file
diff --git a/specs/001-as-a-first/tasks.md b/specs/001-as-a-first/tasks.md
new file mode 100644
index 0000000000..65f6120ed2
--- /dev/null
+++ b/specs/001-as-a-first/tasks.md
@@ -0,0 +1,146 @@
+# Tasks: Mermaid ERD Diagram Documentation
+
+**Input**: Design documents from `/specs/001-as-a-first/`
+**Prerequisites**: plan.md (required), research.md, data-model.md, contracts/
+
+## Execution Flow (main)
+```
+1. Load plan.md from feature directory
+   → If not found: ERROR "No implementation plan found"
+   → Extract: tech stack, libraries, structure
+2. Load optional design documents:
+   → data-model.md: Extract entities → model tasks
+   → contracts/: Each file → contract test task
+   → research.md: Extract decisions → setup tasks
+3. Generate tasks by category:
+   → Setup: project init, dependencies, linting
+   → Tests: contract tests, integration tests
+   → Core: models, services, CLI commands
+   → Integration: DB, middleware, logging
+   → Polish: unit tests, performance, docs
+4. Apply task rules:
+   → Different files = mark [P] for parallel
+   → Same file = sequential (no [P])
+   → Tests before implementation (TDD)
+5. Number tasks sequentially (T001, T002...)
+6. Generate dependency graph
+7. Create parallel execution examples
+8. Validate task completeness:
+   → All contracts have tests?
+   → All entities have models?
+   → All endpoints implemented?
+9. Return: SUCCESS (tasks ready for execution)
+```
+
+## Format: `[ID] [P?] Description`
+- **[P]**: Can run in parallel (different files, no dependencies)
+- Include exact file paths in descriptions
+
+## Path Conventions
+- **Web app**: `backend/src/`, `frontend/src/`
+- Paths shown below assume web application structure - adjust based on plan.md structure
+
+## Phase 3.1: Setup
+- [x] T001 Create project structure for ERD generation module
+- [x] T002 Initialize Python dependencies for ERD generation (SQLModel, Mermaid, pre-commit) using uv in the ./backend directory.
+- [x] T003 [P] Configure linting and formatting tools for ERD module
+- [x] T003a [P] Add multi-file model discovery capability to ERD Generator
+
+## Phase 3.2: Tests First (TDD) ⚠️ MUST COMPLETE BEFORE 3.3
+**CRITICAL: These tests MUST be written and MUST FAIL before ANY implementation**
+- [x] T004 [P] Contract test CLI interface in tests/contract/test_cli_interface.py
+- [x] T005 [P] Contract test pre-commit hook in tests/contract/test_pre_commit_hook.py
+- [x] T006 [P] Contract test validation system in tests/contract/test_validation_contract.py
+- [x] T007 [P] Integration test ERD generation workflow in tests/integration/test_erd_workflow.py
+- [x] T008 [P] Integration test automatic update workflow in tests/integration/test_auto_update.py
+- [x] T009 [P] Integration test error handling workflow in tests/integration/test_error_handling.py
+
+## Phase 3.3: Core Implementation (ONLY after tests are failing)
+- [x] T010 [P] ERD Generator entity in backend/app/erd_generator.py
+- [x] T011 [P] Model Metadata entity in backend/app/erd_models.py
+- [x] T012 [P] ERD Output entity in backend/app/erd_output.py
+- [x] T013 [P] Entity Definition entity in backend/app/erd_entities.py
+- [x] T014 [P] Field Definition entity in backend/app/erd_fields.py
+- [x] T015 [P] Relationship Definition entity in backend/app/erd_relationships.py
+- [x] T016 CLI script generate_erd in backend/scripts/generate_erd.py
+- [x] T017 Pre-commit hook integration in .pre-commit-config.yaml
+- [x] T018 Validation system implementation in backend/app/erd_validation.py
+
+## Phase 3.4: Integration
+- [x] T019 Connect ERD Generator to SQLModel introspection
+- [x] T020 Integrate CLI with file system operations
+- [x] T021 Connect pre-commit hook to ERD generation workflow
+- [x] T022 Integrate validation system with ERD generation
+
+## Phase 3.5: Polish
+- [x] T023 [P] Unit tests for ERD Generator in tests/unit/test_erd_generator.py
+- [x] T024 [P] Unit tests for Model Metadata in tests/unit/test_erd_models.py
+- [x] T025 [P] Unit tests for validation system in tests/unit/test_erd_validation.py
+- [x] T026 Performance tests for ERD generation (<30 seconds for schemas with up to 20 tables and 100 fields)
+- [x] T027 [P] Update documentation in docs/database/erd.md
+- [x] T028 [P] Update constitution with ERD requirements in .specify/memory/constitution.md
+- [x] T029 [P] Update plan template with ERD checks in .specify/templates/plan-template.md
+- [x] T030 [P] Update tasks template with ERD maintenance in .specify/templates/tasks-template.md
+- [x] T031 Remove duplication and optimize code
+- [x] T032 Run manual-testing.md validation
+
+## Dependencies
+- Tests (T004-T009) before implementation (T010-T018)
+- T010 blocks T003a (model discovery must be implemented first)
+- T003a blocks T019 (discovery needed before SQLModel introspection)
+- T016 blocks T020
+- T017 blocks T021
+- T018 blocks T022
+- Implementation before polish (T023-T032)
+
+## Parallel Example
+```
+# Launch T004-T009 together:
+Task: "Contract test CLI interface in tests/contract/test_cli_interface.py"
+Task: "Contract test pre-commit hook in tests/contract/test_pre_commit_hook.py"
+Task: "Contract test validation system in tests/contract/test_validation_contract.py"
+Task: "Integration test ERD generation workflow in tests/integration/test_erd_workflow.py"
+Task: "Integration test automatic update workflow in tests/integration/test_auto_update.py"
+Task: "Integration test error handling workflow in tests/integration/test_error_handling.py"
+```
+
+## Notes
+- [P] tasks = different files, no dependencies
+- Verify tests fail before implementing
+- Commit after each task
+- Avoid: vague tasks, same file conflicts
+
+## Task Generation Rules
+*Applied during main() execution*
+
+1. **From Contracts**:
+   - Each contract file → contract test task [P]
+   - CLI interface → implementation task
+   - Pre-commit hook → integration task
+   - Validation system → implementation task
+   
+2. **From Data Model**:
+   - Each entity → model creation task [P]
+   - ERD Generator → core implementation task
+   - Model Metadata → core implementation task
+   - ERD Output → core implementation task
+   
+3. **From User Stories**:
+   - Each story → integration test [P]
+   - ERD generation workflow → integration test
+   - Automatic update workflow → integration test
+   - Error handling workflow → integration test
+
+4. **Ordering**:
+   - Setup → Tests → Models → Services → Endpoints → Polish
+   - Dependencies block parallel execution
+
+## Validation Checklist
+*GATE: Checked by main() before returning*
+
+- [x] All contracts have corresponding tests
+- [x] All entities have model tasks
+- [x] All tests come before implementation
+- [x] Parallel tasks truly independent
+- [x] Each task specifies exact file path
+- [x] No task modifies same file as another [P] task