[Feature]: Refactor Folder Structure to Feature-Based Layered Architecture

[Harmeet10000]

Prerequisites

• I have searched the existing issues to avoid duplicates
• I understand that this is just a suggestion and might not be implemented

Problem Statement

Update the project’s folder structure to follow a Feature-Based Layered Architecture (Vertical Slice Architecture), with clear separation for chains, graphs, shared, and core folders. This will improve maintainability, scalability, and team collaboration.

Proposed Solution

Why

• High Cohesion: Related code stays together
• Low Coupling: Features are independent
• Easy Navigation: All code for a feature in one place
• Scalability: Easily add features without touching existing ones
• Team Collaboration: Teams can own entire features

---

Proposed Structure

src/
├── api/                           # API Layer (Routes)
├── features/                      # Feature Modules
│   ├── chat/
│   │   ├── api/
│   │   ├── services/
│   │   ├── repositories/
│   │   ├── models/
│   │   ├── agents/
│   │   ├── chains/
│   │   ├── tools/
│   │   ├── utils/
│   │   └── tests/
│   ├── rag/
│   │   ├── api/
│   │   ├── services/
│   │   ├── repositories/
│   │   ├── models/
│   │   ├── chains/
│   │   └── tests/
│   ├── documents/
│   ├── crawl/
│   ├── mcp_agents/
│   └── workflows/
│       ├── graphs/
├── core/                          # Shared/Core Layer
│   ├── config/
│   ├── database/
│   ├── cache/
│   ├── langchain/
│   ├── logging/
│   └── exceptions/
├── shared/                        # Shared Utilities
│   ├── schemas/
│   ├── utils/
│   └── constants/
└── main.py

• Include folders for:
  • chains (conversations, rag, agents)
  • graphs (components, states, workflows)
  • shared (schemas, utils, constants)
  • core (database, cache, config, langchain, etc.)

---

Migration Guide

# 1. Create feature directories
mkdir -p src/features/chat/{api,services,repositories,models,chains,agents,tools,utils,tests}

# 2. Move files into appropriate feature/module folders
# Example:
mv src/api/endpoints/chat.py src/features/chat/api/routes.py
mv src/services/chat_service.py src/features/chat/services/
mv src/models/chat.py src/features/chat/models/

# 3. Update imports throughout the codebase
# e.g., from src.services.chat_service import ChatService
# -> from features.chat.services.chat_service import ChatService

# 4. Add __init__.py files where needed
touch src/features/chat/{__init__,api/__init__,services/__init__}.py

# 5. Repeat for other features/modules

---

Alternatives Considered

Best Practices

• Keep API thin: Move business logic to service layer
• Use dependency injection: For database, repositories, and services
• Keep features independent: Use interfaces/protocols where possible
• Shared/core layers: For cross-cutting concerns and utilities

Additional Context

References

• See issue description for architecture diagrams, migration tips, and code examples.

---

**Let's use this issue to discuss and track migration progress! **

Priority

High

[github-actions]

👋 Welcome to Production-Grade Auth Template!

Thank you for opening your first issue! We're excited to have you as part of our community.

Before we proceed, please ensure:

• You've searched existing issues to avoid duplicates
• You've provided a clear description of the problem
• You've included steps to reproduce (if applicable)
• You've specified your environment details

Our maintainers will review your issue soon. Feel free to join our discussions and contribute to making this project better! 🚀

Useful Resources:

• 📖 Documentation
• 🐛 Bug Report Template
• ✨ Feature Request Template

[Harmeet10000]

┌─────────────────────────────────────────────────────────────────────┐
│                          API LAYER (FastAPI)                        │
│                     Entry Points for All Features                   │
└───────────┬─────────────────────────────────────────┬───────────────┘
            │                                         │
    ┌───────▼─────────┐                      ┌───────▼─────────┐
    │  Feature: Chat  │                      │  Feature: RAG   │
    │                 │                      │                 │
    │  ┌───────────┐  │                      │  ┌───────────┐  │
    │  │   API     │  │ ◄────────────────►  │  │   API     │  │
    │  └─────┬─────┘  │     Can interact     │  └─────┬─────┘  │
    │        │        │                      │        │        │
    │  ┌─────▼─────┐  │                      │  ┌─────▼─────┐  │
    │  │  Service  │  │                      │  │  Service  │  │
    │  └─────┬─────┘  │                      │  └─────┬─────┘  │
    │        │        │                      │        │        │
    │  ┌─────▼─────┐  │                      │  ┌─────▼─────┐  │
    │  │Repository │  │                      │  │Repository │  │
    │  └─────┬─────┘  │                      │  └─────┬─────┘  │
    │        │        │                      │        │        │
    │  ┌─────▼─────┐  │                      │  ┌─────▼─────┐  │
    │  │  Models   │  │                      │  │  Models   │  │
    │  └───────────┘  │                      │  └───────────┘  │
    └─────────────────┘                      └─────────────────┘
            │                                         │
            └─────────────────┬───────────────────────┘
                              │
                    ┌─────────▼─────────┐
                    │   Shared/Core     │
                    │   - Database      │
                    │   - Cache         │
                    │   - Config        │
                    │   - Utils         │
                    └───────────────────┘

[Harmeet10000]

Best Practices

1. Keep Layers Thin

# ❌ BAD: Business logic in API layer
@router.post("/chat")
async def create_chat(request: ChatRequest):
    # DON'T put business logic here
    conversation = db.conversations.find_one(...)
    response = llm.invoke(...)
    db.messages.insert_one(...)
    return response

# ✅ GOOD: Delegate to service
@router.post("/chat")
async def create_chat(
    request: ChatRequest,
    service: ChatService = Depends()
):
    return await service.process_message(request.message)

2. Use Dependency Injection

# ✅ GOOD: Inject dependencies
class ChatService:
    def __init__(
        self,
        repo: ChatRepository,
        cache: ChatCacheRepository
    ):
        self.repo = repo
        self.cache = cache

3. Keep Features Independent

# ✅ GOOD: Use interfaces/protocols
from typing import Protocol

class MessageSender(Protocol):
    async def send(self, message: str) -> str: ...

# Features depend on interface, not implementation
class ChatService:
    def __init__(self, sender: MessageSender):
        self.sender = sender