# Architecture

Retold Data Service orchestrates several Retold modules into a unified service that turns a schema into a running API.

## Component Stack

<!-- bespoke diagram: edit diagrams/component-stack.mmd or .hints.json, then: npx pict-renderer-graph build ../../meadow/retold-data-service/docs -->
![Component Stack](diagrams/component-stack.svg)

## Initialization Flow

The `initializeService()` method runs an ordered sequence of asynchronous steps using Fable's Anticipate pattern:

<!-- bespoke diagram: edit diagrams/initialization-flow.mmd or .hints.json, then: npx pict-renderer-graph build modules/meadow/retold-data-service/docs -->
![Initialization Flow](diagrams/initialization-flow.svg)

## Component Diagram

<!-- bespoke diagram: edit diagrams/component-diagram.mmd or .hints.json, then: npx pict-renderer-graph build modules/meadow/retold-data-service/docs -->
![Component Diagram](diagrams/component-diagram.svg)

## How It Works

1. **Registration** -- `RetoldDataService` is registered with Fable's service manager and instantiated with options
2. **Server Setup** -- Orator and its Restify service server are registered and configured
3. **Initialization** -- calling `initializeService()` triggers an ordered sequence:
   - `onBeforeInitialize()` -- your custom pre-initialization logic
   - Orator web server start (if `AutoStartOrator` is true)
   - Persistence engine initialization (loads the storage provider module)
   - `onInitialize()` -- your custom initialization logic
   - Data endpoint initialization (loads model, creates DALs and endpoints)
   - `onAfterInitialize()` -- your custom post-initialization logic
4. **Serving** -- the Restify server listens for HTTP requests and routes them through Meadow Endpoints to the DAL

## Key Objects

After initialization, these objects are available on the Fable instance:

| Object | Type | Description |
|--------|------|-------------|
| `fable.RetoldDataService` | Service | The data service instance |
| `fable.Orator` | Service | The Orator API server |
| `fable.OratorServiceServer` | Service | The Restify server |
| `fable.DAL.<Entity>` | Meadow | DAL for each entity in the model |
| `fable.MeadowEndpoints.<Entity>` | MeadowEndpoints | Endpoint controller for each entity |

## Service Provider Pattern

Retold Data Service follows the Fable service provider pattern:

```javascript
const libFableServiceProviderBase = require('fable-serviceproviderbase');

class RetoldDataService extends libFableServiceProviderBase
{
	constructor(pFable, pOptions, pServiceHash)
	{
		super(pFable, pOptions, pServiceHash);
		this.serviceType = 'RetoldDataService';
	}
}
```

This means it inherits logging, configuration access, and service lifecycle management from the base class.  You register it with Fable's service manager like any other service:

```javascript
const libRetoldDataService = require('retold-data-service');

_Fable.serviceManager.addServiceType('RetoldDataService', libRetoldDataService);
let _DataService = _Fable.serviceManager.instantiateServiceProvider('RetoldDataService',
	{
		FullMeadowSchemaPath: `${__dirname}/model/`,
		FullMeadowSchemaFilename: 'MeadowModel-Extended.json',
		StorageProvider: 'MySQL',
		StorageProviderModule: 'meadow-connection-mysql',
		AutoStartOrator: true
	});
```

Once instantiated, the service is available at `_Fable.RetoldDataService` and can be initialized with `initializeService()`.