Added documentation

README.md

@@ -33,23 +33,25 @@ You can then update configs in the `.env` files to customize your configurations
 
 ## Bootstrap & development mode
 
-You have two options to start this dockerized setup, depending on whether you want to reset the database:
-### Option A: Run migrations & seed data (will reset DB)
+You have two options to start this dockerized setup:
+### Option A: Run migrations & seed data
 
 Use the prestart profile to automatically run database migrations and seed data.
-This profile also resets the database, so use it only when you want a fresh start.
+This does **not** reset/drop the database.
 ```bash
-docker compose --profile prestart up
+docker compose --profile prestart up prestart
 ```
 
-### Option B: Start normally without resetting DB
+### Option B: Start normally
 
-If you don't want to reset the database, start the project directly:
+Start the project directly:
 ```bash
 docker compose watch
 ```
 This will start all services in watch mode for development — ideal for local iterations.
 
+Backend is exposed at `http://localhost:8001` (container port `8000` mapped to host `8001`).
+
 ### Rebuilding Images
 
 ```bash
@@ -77,7 +79,7 @@ This includes using Docker Compose, custom local domains, `.env` configurations,
 
 ## Release Notes
 
-Check the file [release-notes.md](./release-notes.md).
+Release notes file is not currently maintained in this repository.
 
 ## Credits
 

backend/README.md

@@ -89,7 +89,7 @@ To test the backend run:
 $ bash ./scripts/test.sh
 ```
 
-The tests run with Pytest, modify and add tests to `./backend/tests/`.
+The tests run with Pytest, modify and add tests to `./backend/app/tests/`.
 
 If you use GitHub Actions the tests will run automatically.
 
@@ -140,6 +140,16 @@ predictions.csv contains original text, anonymized output, ground-truth masked t
 
 metrics.json contains entity-level precision, recall, and F1 per PII type.
 
+## Validator configuration guide
+
+Detailed validator configuration reference:
+`backend/app/core/validators/README.md`
+
+## API usage guide
+
+Detailed API usage and end-to-end request examples:
+`backend/app/api/API_USAGE.md`
+
 ### Test running stack
 
 If your stack is already up and you just want to run the tests, you can use:
@@ -172,7 +182,7 @@ Make sure you create a "revision" of your models and that you "upgrade" your dat
 $ docker compose exec backend bash
 ```
 
-* Alembic is already configured to import your SQLModel models from `./backend/app/models.py`.
+* Alembic is configured with SQLModel models under `./backend/app/models/`.
 
 * After changing a model (for example, adding a column), inside the container, create a revision, e.g.:
 
@@ -216,6 +226,20 @@ echo -n "your-plain-text-token" | shasum -a 256
 
 Set the resulting digest as `AUTH_TOKEN` in your `.env` / `.env.test`.
 
+## Multi-tenant API Key Configuration
+
+Ban List APIs use `X-API-KEY` auth instead of bearer token auth.
+
+Required environment variables:
+- `KAAPI_AUTH_URL`: Base URL of the Kaapi auth service used to verify API keys.
+- `KAAPI_AUTH_TIMEOUT`: Timeout in seconds for auth verification calls.
+
+At runtime, the backend calls:
+- `GET {KAAPI_AUTH_URL}/apikeys/verify`
+- Header: `X-API-KEY: ApiKey <token>`
+
+If verification succeeds, tenant's scope (`organization_id`, `project_id`) is resolved from the auth response and applied to Ban List CRUD operations.
+
 ## Guardrails AI Setup
 1. Ensure that the .env file contains the correct value from `GUARDRAILS_HUB_API_KEY`. The key can be fetched from [here](https://hub.guardrailsai.com/keys).
 
@@ -244,7 +268,7 @@ Enter API Key below leave empty if you want to keep existing token [HBPo]
 ```
 
 To install any validator from Guardrails Hub:
-```
+```bash
 guardrails hub install hub://guardrails/<validator-name>
 
 Example -
@@ -254,13 +278,13 @@ guardrails hub install hub://guardrails/ban_list
 ## Adding a new validator from Guardrails Hub
 To add a new validator from the Guardrails Hub to this project, follow the steps below.
 
-1. In the `backend/app/models` folder, create a new Python file called `<validator_name>_safety_validator_config.py`. Add the following code there:
+1. In the `backend/app/core/validators/config` folder, create a new Python file called `<validator_name>_safety_validator_config.py`. Add the following code there:
 
-```
+```python
 from guardrails.hub import # validator name from Guardrails Hub
 from typing import List, Literal
 
-from app.models.base_validator_config import BaseValidatorConfig
+from app.core.validators.config.base_validator_config import BaseValidatorConfig
 
 class <Validator-name>SafetyValidatorConfig(BaseValidatorConfig):
     type: Literal["<validator-name>"]
@@ -272,11 +296,11 @@ class <Validator-name>SafetyValidatorConfig(BaseValidatorConfig):
 
 For example, this is the code for [BanList validator](https://guardrailsai.com/hub/validator/guardrails/ban_list).
 
-```
+```python
 from guardrails.hub import BanList
 from typing import List, Literal
 
-from app.models.base_validator_config import BaseValidatorConfig
+from app.core.validators.config.base_validator_config import BaseValidatorConfig
 
 
 class BanListSafetyValidatorConfig(BaseValidatorConfig):
@@ -291,14 +315,14 @@ class BanListSafetyValidatorConfig(BaseValidatorConfig):
 
 ```
 
-2. In `backend/app/guardrail_config.py`, add the newly created config class to `ValidatorConfigItem`.
+2. In `backend/app/schemas/guardrail_config.py`, add the newly created config class to `ValidatorConfigItem`.
 
 ## How to add custom validators?
 To add a custom validator to this project, follow the steps below.
 
 1. Create the custom validator class. Take a look at the `backend/app/core/validators/gender_assumption_bias.py` as an example. Each custom validator should contain an `__init__` and `_validator` method. For example,
 
-```
+```python
 from guardrails import OnFailAction
 from guardrails.validators import (
     FailResult,
@@ -324,12 +348,12 @@ class <Validator-Name>(Validator):
         # add logic for validation
 ```
 
-2. In the `backend/app/models` folder, create a new Python file called `<validator_name>_safety_validator_config.py`. Add the following code there:
+2. In the `backend/app/core/validators/config` folder, create a new Python file called `<validator_name>_safety_validator_config.py`. Add the following code there:
 
-```
+```python
 from typing import List, Literal
 
-from app.models.base_validator_config import BaseValidatorConfig
+from app.core.validators.config.base_validator_config import BaseValidatorConfig
 
 class <Validator-name>SafetyValidatorConfig(BaseValidatorConfig):
     type: Literal["<validator-name>"]
@@ -341,9 +365,9 @@ class <Validator-name>SafetyValidatorConfig(BaseValidatorConfig):
 
 For example, this is the code for GenderAssumptionBias validator.
 
-```
+```python
 from typing import ClassVar, List, Literal, Optional
-from app.models.base_validator_config import BaseValidatorConfig
+from app.core.validators.config.base_validator_config import BaseValidatorConfig
 from app.core.enum import BiasCategories
 from app.core.validators.gender_assumption_bias import GenderAssumptionBias
 
@@ -358,4 +382,4 @@ class GenderAssumptionBiasSafetyValidatorConfig(BaseValidatorConfig):
         )
 ```
 
-2. In `backend/app/guardrail_config.py`, add the newly created config class to `ValidatorConfigItem`.
+3. In `backend/app/schemas/guardrail_config.py`, add the newly created config class to `ValidatorConfigItem`.