graph_rag_server/docs/directory-structure.md

RAG System Directory Structure

This document describes the new directory structure created for the RAG System refactoring.

Overview

The new structure follows a clean layered architecture with four main layers:

• Domain Layer: Core business logic and domain models
• Application Layer: Use cases and application services
• Infrastructure Layer: Technical capabilities and external integrations
• Presentation Layer: HTTP request/response handling

Directory Structure

rag_system/
├── src/                              # Source code
│   ├── domain/                       # Domain layer
│   │   ├── vector_search/            # Vector search domain
│   │   ├── document_parsing/         # Document parsing domain
│   │   ├── knowledge_base/           # Knowledge base domain
│   │   └── shared/                   # Shared domain concepts
│   │
│   ├── application/                  # Application layer
│   │   ├── vector_search/            # Vector search use cases
│   │   ├── document_parsing/         # Document parsing use cases
│   │   ├── knowledge_base/           # Knowledge base use cases
│   │   └── shared/                   # Shared application concepts
│   │
│   ├── infrastructure/               # Infrastructure layer
│   │   ├── vector_db/                # Vector database implementations
│   │   ├── database/                 # Database and ORM models
│   │   ├── external_services/        # External service integrations
│   │   ├── file_storage/             # File storage implementations
│   │   └── parsers/                  # Document parser implementations
│   │
│   ├── presentation/                 # Presentation layer
│   │   ├── api/                      # API routers
│   │   │   └── v1/                   # API version 1 endpoints
│   │   └── schemas/                  # Request/response schemas
│   │
│   ├── config/                       # Configuration management
│   └── shared/                       # Shared utilities
│
├── tests/                            # Test suite
│   ├── unit/                         # Unit tests
│   │   ├── domain/                   # Domain layer tests
│   │   ├── application/              # Application layer tests
│   │   └── infrastructure/           # Infrastructure layer tests
│   ├── integration/                  # Integration tests
│   │   ├── api/                      # API integration tests
│   │   └── database/                 # Database integration tests
│   ├── e2e/                          # End-to-end tests
│   └── fixtures/                     # Test fixtures and data
│
├── docs/                             # Documentation
├── scripts/                          # Utility scripts
└── docker/                           # Docker configuration

Layer Responsibilities

Domain Layer (src/domain/)

• Core business logic and rules
• Domain entities and value objects
• Domain services
• Repository interfaces
• Domain events
• No external framework dependencies

Application Layer (src/application/)

• Coordinates domain objects to complete use cases
• Defines application service interfaces
• Handles transaction boundaries
• DTO (Data Transfer Object) conversions
• Command and query handlers

Infrastructure Layer (src/infrastructure/)

• Data persistence implementations
• External service integrations
• File system operations
• Message queues
• Cache implementations

Presentation Layer (src/presentation/)

• HTTP request and response handling
• API route definitions
• Request validation and response serialization
• Exception to HTTP error conversion
• Middleware (logging, authentication, CORS, etc.)

Configuration (src/config/)

• Centralized configuration management
• Environment-specific settings
• Database configuration
• Vector database configuration
• Logging configuration

Shared Utilities (src/shared/)

• Common utilities and helper functions
• Base exceptions
• Logging utilities

Test Structure (tests/)

• Unit tests: Test individual components in isolation
• Integration tests: Test component interactions
• E2E tests: Test complete user scenarios
• Fixtures: Shared test data and fixtures

Status

✅ Task 1.1 completed: All directories and __init__.py files have been created successfully.

Next Steps

The next tasks in Phase 1 are:

• Task 1.2: Set up configuration management system
• Task 1.3: Write configuration management unit tests
• Task 1.4: Establish testing framework
• Task 1.5: Configure logging system
• Task 1.6: Write logging system tests
• Task 1.7: Configure CI/CD pipeline