docs(readme): update architecture diagram and add explanatory text

[nanotaboada]

This change is 

Summary by CodeRabbit

• Documentation
  • Added a comprehensive GitHub issue template for structured bug reports (description, reproduction steps, expected/actual behavior, environment, and possible solutions).
  • Expanded the README with detailed layered-architecture guidance, dependency-injection descriptions, and an enhanced architecture diagram.
  • Updated contributor instructions to include an example co-author line in commit message guidance.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: defc8110-4157-421d-b205-ccf42184bc00

📥 Commits

Reviewing files that changed from the base of the PR and between 29087e6 and 502b256.

📒 Files selected for processing (1)

• README.md

🚧 Files skipped from review as they are similar to previous changes (1)

• README.md

---

Walkthrough

Adds a new GitHub bug report issue template, a small co-author line update in copilot instructions, and expands README with detailed layered-architecture documentation and an updated Mermaid diagram describing DI, Pydantic, and lifecycle responsibilities.

Changes

Cohort / File(s)	Summary
GitHub configuration .github/ISSUE_TEMPLATE/bug_report.md, .github/copilot-instructions.md	Adds a new structured bug report issue template (front matter + sections: Description, Steps, Expected/Actual, Environment, etc.); adds a single co-author line to the copilot instructions example commit message.
Project documentation README.md	Extends architecture documentation: layered architecture (Initialization, HTTP, Business, Data), DI via FastAPI Depends(), Pydantic usage, composition root pattern, arrow semantics, and an expanded Mermaid diagram with additional nodes and styling adjustments.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• docs(readme): refresh structure with Mermaid diagram and new sections #510: Related README and .github/copilot-instructions.md modifications (overlapping architecture/diagram and copilot instruction edits).
• docs: optimize AI agent instructions for token efficiency #471: Changes to .github/copilot-instructions.md that intersect with the copilot instruction update here.
• chore: update structure diagram #331: Updates README project/structure diagram content similar to this PR's README diagram revisions.

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title uses Conventional Commits format (docs:), is descriptive and specific, and is 66 characters - well under the 80-character limit.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/architecture-diagram

• 🛠️ sync documentation: Commit on current branch
• 🛠️ sync documentation: Create PR
• 🛠️ enforce http error handling: Commit on current branch
• 🛠️ enforce http error handling: Create PR
• 🛠️ idiomatic review: Commit on current branch
• 🛠️ idiomatic review: Create PR
• 🛠️ verify api contract: Commit on current branch
• 🛠️ verify api contract: Create PR

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

Tip

CodeRabbit can scan for known vulnerabilities in your dependencies using OSV Scanner.

OSV Scanner will automatically detect and report security vulnerabilities in your project's dependencies. No additional configuration is required.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (50c0feb) to head (502b256).
⚠️ Report is 4 commits behind head on master.

Additional details and impacted files

@@            Coverage Diff            @@
##            master      #522   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files            3         3           
  Lines          110       110           
=========================================
  Hits           110       110           

Components	Coverage Δ
Services	100.00% <ø> (ø)
Routes	100.00% <ø> (ø)

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

README.md (1)

101-101: Consider the graph direction choice.

The diagram direction was changed from TB (top-to-bottom) to RL (right-to-left). While this is valid, dependency graphs are more commonly rendered top-to-bottom or left-to-right in software architecture documentation. Right-to-left may feel counterintuitive to readers accustomed to LTR reading direction, though it can work if dependencies naturally flow that way.

💡 Alternative: Consider LR (left-to-right) for conventional flow

-graph RL
+graph LR

This would show dependencies flowing left-to-right, which aligns with typical reading direction and common architectural diagram conventions.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@README.md` at line 101, The diagram direction was changed to "graph RL" which
forces right-to-left rendering and may confuse readers; update the graph
direction token to a more conventional flow such as "graph TB" (top-to-bottom)
or "graph LR" (left-to-right) depending on how you want dependencies to read,
i.e., replace "graph RL" with "graph LR" (or "graph TB") in the README's mermaid
diagram header so the dependency flow matches typical architectural conventions.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@README.md`:
- Line 169: The phrasing is reversed: change the clause that reads "SQLAlchemy
holds a soft dependency on `routes`" so it correctly states that `routes` holds
a soft dependency on `SQLAlchemy` (e.g., "routes holds a soft dependency on
`SQLAlchemy` — `AsyncSession` is referenced only as a type annotation in
`Depends()`, without any direct SQLAlchemy method calls at the route level"),
ensuring the subjects `routes` and `SQLAlchemy` are swapped to match the arrow
semantics and diagram.

---

Nitpick comments:
In `@README.md`:
- Line 101: The diagram direction was changed to "graph RL" which forces
right-to-left rendering and may confuse readers; update the graph direction
token to a more conventional flow such as "graph TB" (top-to-bottom) or "graph
LR" (left-to-right) depending on how you want dependencies to read, i.e.,
replace "graph RL" with "graph LR" (or "graph TB") in the README's mermaid
diagram header so the dependency flow matches typical architectural conventions.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: b16d538d-a091-415c-8dc2-6d547870dd59

📥 Commits

Reviewing files that changed from the base of the PR and between 50c0feb and 29087e6.

📒 Files selected for processing (3)

• .github/ISSUE_TEMPLATE/bug_report.md
• .github/copilot-instructions.md
• README.md

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud