Raven Tales

⚙️ Under the Hood: The Technology Powering RavenTales

RavenTales is engineered as a modern, scalable application using a microservices architecture. This design approach ensures that the platform is both resilient and maintainable, allowing for independent development and scaling of each core feature. The backend services are built with .NET, leveraging the principles of Clean Architecture and Domain-Driven Design (DDD) to create a system that is robust, well-organized, and easy to evolve. To ensure consistency across development and deployment environments, the entire application is containerized using Docker. The user-facing side of the application is a dynamic and responsive single-page application (SPA) built with React. This allows for a seamless and interactive user experience, enabling fluid navigation through stories and vocabulary lists without constant page reloads. Each microservice communicates via APIs and manages its own dedicated SQL Server database, promoting service independence and preventing data bottlenecks.

🏛️ Architectural Deep Dive: The StoryService Engine

While the high-level technology stack provides an overview, the core of RavenTales lies in its robust and meticulously designed StoryService. This section details the internal workings of the story generation, retrieval, and user interaction logic, demonstrating a commitment to reliability, efficiency, and clean architecture.

The AI Generation Core

The interaction with the AI model is a controlled, end-to-end process designed for consistency. When a new story is needed, the service first constructs a highly specific prompt that forces the AI to return a response in a strict, predictable JSON format. This eliminates the risk of receiving unstructured text and ensures the data perfectly maps to the application's needs. As a final check, the service programmatically validates the story's language and level to match the original request, correcting for any potential AI drift and guaranteeing data integrity.

Orchestration and Business Logic

The Story Service acts as the central orchestrator for all business logic. Its most critical function is delivering stories to the user efficiently. When a user requests a story, the service employs a "reuse-first" strategy—a key design choice to conserve costs and reduce latency. It intelligently searches the database for an existing story that matches the user's criteria but which they haven't read yet. A brand-new story is generated via the AI service only when no suitable match is found, ensuring a seamless experience while being resource-conscious. Beyond generation, the service provides all the necessary functionality for a rich user experience. It allows users to browse and filter the entire story library, retrieve the full text of a story after selecting its card, and view a personalized feed of recommendations. It also handles all personal user data, such as tracking reading history and managing a collection of bookmarked or saved stories.

Data Persistence and Design Principles

The data layer is designed with a clear separation of concerns. The main Story table contains no user-specific fields. All personalization, such as reading history and bookmarks, is stored in separate, dedicated tables linked by a user ID. This decoupled design is fundamental to the architecture, ensuring that the core library of stories remains clean and that user data is managed independently. This adherence to Clean Architecture principles means all requests flow through the service layer, which protects the integrity and business rules of the data.