docs: Add comprehensive guide for creating services and API v2 integration

[hariombalhara]

What does this PR do?

This PR adds comprehensive documentation to the .agents/knowledge-base.md file explaining how to create services in the packages/features directory and properly integrate them with API v2 using the platform-libraries pattern.

The documentation provides:

• An overview of the layered service architecture in Cal.com
• Step-by-step guide for creating base services with dependency injection
• Instructions for exporting services through platform-libraries
• Examples of creating API v2 repository wrappers and services
• Module configuration for NestJS dependency injection
• Common patterns and troubleshooting tips

Context: This documentation was created to help developers understand the proper architecture for services and avoid common mistakes like:

• Importing directly from packages/features in API v2 (violates architecture)
• Not using dependency injection properly
• Missing module provider registrations

The guide uses a generic NotificationService example to demonstrate the patterns without being tied to any specific feature.

---

Link to Devin run: https://app.devin.ai/sessions/9a569d953f0a4e78a72149b53a14f6b3
Requested by: @hariombalhara ([email protected])

Visual Demo

N/A - Documentation only

Mandatory Tasks (DO NOT REMOVE)

• I have self-reviewed the code (A decent size PR without self-review might be rejected).
• I have updated the developer docs in /docs if this PR makes changes that would require a documentation change. N/A - This PR is the documentation update.
• I confirm automated tests are in place that prove my fix is effective or that my feature works. N/A - Documentation changes cannot be automatically tested.

How should this be tested?

This is a documentation-only PR. Testing involves:

1. Accuracy Review: Verify the documented patterns match actual Cal.com conventions

   • Check that the 5-layer architecture (Base Service → Platform Library → API v2 Service → Repository → Module) is correct
   • Confirm the dependency injection patterns are accurate
   • Validate code examples against real implementations like RegularBookingService and HashedLinkService

2. Completeness Review: Ensure the guide covers all necessary steps

   • Are there any missing steps in the service creation flow?
   • Are there important edge cases or considerations not mentioned?
   • Is the troubleshooting section comprehensive?

3. Clarity Review: Assess if the documentation is clear and easy to follow

   • Are the examples easy to understand?
   • Is the architecture explanation clear?
   • Would a new developer be able to follow this guide successfully?

Human Review Checklist

Critical items to verify:

• Architecture Pattern: Confirm the documented 5-layer architecture (Base Service → Platform Libraries → API v2 Service → API v2 Repository → API v2 Module) matches the team's intended design
• Dependency Injection Approach: Verify that optional dependencies with fallback instantiation (deps?: ServiceDeps) is the correct pattern for base services
• Platform Libraries Pattern: Confirm that API v2 should never import directly from packages/features and must go through platform-libraries
• NestJS Patterns: Validate that the documented use of @Injectable(), module providers, and dependency injection follows NestJS best practices
• Code Examples: Review the NotificationService example for correctness - ensure it doesn't contain any anti-patterns or misleading code
• Best Practices Section: Confirm the listed best practices align with team standards
• Troubleshooting Section: Check if the common errors listed are actually the most frequent issues developers encounter

Low-risk items:

• Formatting and markdown syntax
• Typos and grammar
• Link accuracy

---

Summary by cubic

Added a clear guide to .agents/knowledge-base.md for creating services in packages/features and integrating them with API v2 through platform-libraries. It covers the 5-layer architecture, DI, NestJS modules/providers, repository wrappers, examples, best practices, and troubleshooting.

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR that start with 'DevinAI' or '@devin'.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

2 Skipped Deployments

Project	Deployment	Preview	Comments	Updated (UTC)
cal	Ignored			Oct 25, 2025 1:49pm
cal-eu	Ignored			Oct 25, 2025 1:49pm