> ## Documentation Index
> Fetch the complete documentation index at: https://docs.backant.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Directory Structure

> A tour of every folder and file in a BackAnt generated project.

Running `ant generate api my-api` produces the following structure:

```
my-api/
├── api/
│   ├── apis/
│   │   └── aws/
│   │       └── AWSClient.py
│   ├── decorators/
│   │   └── token_required.py
│   ├── helper/
│   │   ├── DBSession.py
│   │   └── execution_tracking/
│   │       ├── APIException.py
│   │       └── Logger.py
│   │   └── functions/
│   │       ├── extract_fields.py
│   │       ├── log_directory_contents.py
│   │       ├── update_dict.py
│   │       ├── update_measurement.py
│   │       └── validation_error.py
│   ├── models/
│   │   └── Default_model.py
│   ├── repositories/
│   │   ├── Repository.py
│   │   └── default_repository.py
│   ├── routes/
│   │   └── default_route.py
│   ├── schemas/
│   │   └── PostDefault_schema.py
│   ├── services/
│   │   └── default_service.py
│   ├── startup/
│   │   ├── Alchemy.py
│   │   └── Environment.py
│   └── app.py
├── .github/
│   └── workflows/
│       └── build_and_push_to_ecr.yml
├── .env
├── docker-compose.yml
├── docker-compose-prod.yml
├── Dockerfile
└── requirements.txt
```

## Top-level files

| File                      | Description                                                                                     |
| ------------------------- | ----------------------------------------------------------------------------------------------- |
| `Dockerfile`              | Builds the Flask app image using `python:3.11-slim-buster`, runs with `gunicorn` on port `5000` |
| `docker-compose.yml`      | Starts PostgreSQL and the Flask backend together for local development                          |
| `docker-compose-prod.yml` | Production compose file pointing at your ECR image                                              |
| `.env`                    | Local environment variables — never commit real credentials                                     |
| `requirements.txt`        | All Python dependencies                                                                         |

## `api/` — application root

Everything inside `api/` is the Flask application. The `Dockerfile` copies this directory into `/app` and sets it as the working directory.

### `app.py`

The Flask application factory. Creates the app, registers CORS, initializes the database, loads `.env`, and registers all blueprints. Every new route generated by `ant generate route` is automatically imported and registered here.

### `startup/`

| File             | Description                                                                                                                                                                                            |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Alchemy.py`     | Creates the SQLAlchemy engine and `db_session`. Defines `Base` (the declarative base all models inherit from). `init_db()` imports all models and calls `Base.metadata.create_all()` to create tables. |
| `Environment.py` | Maps all environment variables to typed class attributes via `os.environ.get()`. Import `myEnvironment` from here instead of reading `os.environ` directly.                                            |

### `routes/`

Flask Blueprints — one file per resource. Each route file defines a blueprint registered at `/<route_name>` and calls the corresponding service. Routes contain no business logic.

### `services/`

Business logic layer — one file per resource. Services receive data from routes, apply logic, call repositories, and return results. All validation, calculations, and orchestration live here.

### `repositories/`

Data access layer — one file per resource. All SQLAlchemy queries live here. Repositories extend `Repository` (the base class in `Repository.py`) which provides `add()`, `add_all()`, and `delete()`.

### `models/`

SQLAlchemy dataclass models — one file per table. Each model inherits from `Base` and uses `@dataclass` to define columns. No methods, no business logic — column definitions only.

### `schemas/`

Marshmallow schemas for request validation. Used in POST/PUT routes to validate incoming JSON before it reaches the service layer.

### `decorators/`

Custom Flask route decorators. The default project ships `token_required` and `role_required` for Bearer token authentication and role-based access.

### `helper/`

Shared utilities available across all layers.

| File                                  | Description                                                                                                                                             |
| ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DBSession.py`                        | Wraps the SQLAlchemy `scoped_session` with `execute()`, `execute_commit()`, `add()`, `add_all()`, and `delete()` — all with automatic rollback on error |
| `execution_tracking/APIException.py`  | Custom exception class with `status_code` and `message`. Register with `@app.errorhandler(APIException)` to return JSON error responses automatically.  |
| `execution_tracking/Logger.py`        | Structured logger that auto-tags each log entry with the calling class and method name.                                                                 |
| `functions/extract_fields.py`         | Extract a subset of keys from a dict using a regex pattern                                                                                              |
| `functions/validation_error.py`       | Converts a marshmallow `ValidationError` into an `APIException(400)`                                                                                    |
| `functions/update_dict.py`            | Merge two dicts and remove `"NaN"` values                                                                                                               |
| `functions/log_directory_contents.py` | Runs `ls -la` on a directory and logs the output                                                                                                        |

### `apis/`

Third-party API client wrappers. The default project ships `AWSClient` — a boto3 session wrapper that supports profile-based, key-based, and ECS task role authentication.

### `.github/workflows/`

A GitHub Actions workflow that builds the Docker image and pushes it to Amazon ECR on every push to `main`. Configure the ECR repository and AWS region in the workflow env vars.