docs: align Development Guide with current repo structure

[Copilot]

This PR refreshes the Development Guide to accurately reflect the current dev branch structure and conventions. The previous guide contained outdated path references and wiki links that no longer matched the actual codebase organization.

Key Changes

Updated directory structure to match reality:

• API routes: src/app/(server)/api/**/route.ts (confirmed no _api prefix or versioning)
• Services: src/app/(server)/services/** (verified actual location)
• Validation: src/lib/validation/** (confirmed with existing schemas)
• Components: src/app/(client)/components/** (matches current structure)
• Utilities: src/lib/utils/** with cn() in classnames.ts

Replaced outdated references:

• Removed wiki links to "Project Structure Guide"
• Added internal crosslinks to architecture.md and getting-started.md
• Updated import examples to use correct aliases from tsconfig.json (@services, @lib, etc.)

Added required shadcn rule:

• Prominent callout box warning not to modify src/shadcn-ui/** files
• Clear guidance to create wrappers in src/app/(client)/components/** instead

Streamlined content:

• Condensed from 464 lines to 131 lines while retaining all essential information
• Focused on actionable patterns rather than workflow process
• Updated examples to reflect current API route structure and service patterns

Summary by CodeRabbit

• Documentation
  • Overhauled the Development Guide with a new title and structure.
  • Added sections: Purpose & Scope, Directory & Path Rules, Middleware Rules, Utilities & Domain Models, Validation Rules, and more.
  • Clarified architecture-first guidance with new examples and patterns; introduced “Routes are thin: validate → delegate → respond.”
  • Updated internal links and cross-references to related guides.
  • Refreshed examples and terminology to current conventions.
  • Updated the “Last updated” date.

[coderabbitai]

Important

Review skipped

Bot user detected.

To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Note

Other AI code review bot(s) detected

CodeRabbit has detected other AI code review bot(s) in this pull request and will avoid duplicating their findings in the review comments. This may lead to a less comprehensive review.

Walkthrough

Restructures docs/development-guide.md: replaces intro with a “Development Guide” title, reorganizes sections, updates guidance, examples, paths, and internal links, adds meta-guidance on routing and architecture placement, replaces historical references, and updates the “Last updated” timestamp to 2025-09-25.

Changes

Cohort / File(s)	Summary
Documentation restructure docs/development-guide.md	Overhauled structure and headings; updated examples and import paths (e.g., app/_api → src/app/(server)/api, validation/domain → src/lib/*); added architecture-oriented guidance and route handling pattern; refreshed internal links; removed outdated references; updated timestamp.

Sequence Diagram(s)

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Suggested labels

📖 Documentation

Poem

A bunny pads through docs so wide,
Repaths made neat, with tidy stride.
Routes are thin—validate, then glide—
To services where truths reside.
New links twinkle, pathways guide;
I thump approval, whiskers pried—
Commit approved, with carrot pride! 🥕

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title Check	✅ Passed	The title succinctly describes the main documentation update by stating that the Development Guide is aligned with the current repository structure, matching the changeset’s goal of updating path references and section headings to reflect the dev branch layout.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull Request Overview

This PR refreshes the Development Guide to accurately reflect the current dev branch structure and conventions, replacing outdated path references and wiki links with verified information.

• Consolidates content from 464 to 154 lines while preserving all essential technical guidance
• Updates all directory paths to match the actual codebase structure with proper import aliases
• Adds critical shadcn/ui modification warning and replaces broken wiki references with internal docs

---

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

[mahid797]

@coderabbitai review

[coderabbitai]

✅ Actions performed

Review triggered.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 2

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between fbc1f06 and 9193afb.

⛔ Files ignored due to path filters (1)

• .coderabbit.yaml is excluded by none and included by none

📒 Files selected for processing (1)

• docs/development-guide.md (1 hunks)

🧰 Additional context used

📓 Path-based instructions (1)

docs/**

⚙️ CodeRabbit configuration file

docs/**: Keep Development Guide aligned with current directory structure and conventions. Update docs when APIs/routes/schemas change.

Files:

• docs/development-guide.md

🪛 markdownlint-cli2 (0.18.1)

docs/development-guide.md

9-9: Blank line inside blockquote

(MD028, no-blanks-blockquote)

---

148-148: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below

(MD022, blanks-around-headings)

---

156-156: Emphasis used instead of a heading

(MD036, no-emphasis-as-heading)

---

156-156: Emphasis style
Expected: underscore; Actual: asterisk

(MD049, emphasis-style)

---

156-156: Emphasis style
Expected: underscore; Actual: asterisk

(MD049, emphasis-style)