language-learning-app/api/architecture.md

Language Learning App API Architecture

This is a HTTP API, written in Python, using the Fastapi framework.

The code should be organised using both Domain Driven Design and Hexagonal Architecture principles.

Domain

The domain directory contains the core logic of my application, not related to specific implementation details.

This is where all of the logic around the actual language learning lives.

Models

In app/domain/models contains the core Domain Entities, i.e. classes that represent objects for core domain processes.

Services

The app/domain/services directory contains modules that encapsulate the "orchestration" or "choreography" of other components of the system to achieve complex, domain actions.

For example:

• TextGenerationService details the step-by-step process of how a series of text is synthesised, audio is generated, parts of speech tagged, timed transcripts generated, etc. which is then used by the learner for language learning.

Outbound

The app/outbound directory contains modules that allow this project to communicate with external systems.

Repositories and persistence

This project uses SQLAlchemy for persistence and a postgresql database for storage. This is the same in local, deployed, and test environments.

Notably the app/outbound/postgres directory contains two modules:

• entities contains definitions of tables in the database. These are how the Domain Entities are serialised, but this code specifically is used for serialisation to, and de-serialisation from, persisted data and into Domain Entities from the models module.
• repositories module contains classes which manage transactions (e.g. CRUD operations) with the psotgresql database, managed through sqlite. Code in the repositories module are what allow Models to be persisted via Entities, allowing all other code to be free of implementation details.

API Clients

Other modules in the wider app/outbound directory are about communicating with specific third-party APIs, notably through HTTP APIs authenticated with an authentication token.

These modules are modelled as Classes.

Example Api Clients in their own modules are:

• AnthropicClient to communicate with Anthorpic's LLM, i.e. Claude, to generate text and synthesis.
• GeminiClient to communicate with Google's Gemini for text-to-speech generation
• DeepgramClient for timestamped speech-to-text transcription