FASTAPI.md

# FASTAPI.md

## STACK

REQUIRED

- Python 3.13+
- FastAPI
- Pydantic 2.x
- Uvicorn

OPTIONAL

- SQLAlchemy
- Alembic
- PostgreSQL

USE_DECLARED_STACK_ONLY

DO_NOT_INTRODUCE_NEW_LIBRARIES_UNLESS_EXPLICITLY_REQUESTED

---

## VERSION_POLICY

PYPROJECT_TOML_IS_SOURCE_OF_TRUTH

REQUIREMENTS_TXT_IS_FALLBACK

USE_DECLARED_VERSIONS_ONLY

DO_NOT_ASSUME_LIBRARY_VERSIONS

DO_NOT_GENERATE_DEPRECATED_PATTERNS

WHEN_VERSION_CONFLICT_EXISTS

FOLLOW_PROJECT_CONFIGURATION

---

## PROJECT_STRUCTURE

```text
app/
├── api/
├── schemas/
├── dependencies/
├── core/
└── main.py

tests/

pyproject.toml
```

THIS_STRUCTURE_IS_AUTHORITATIVE

DO_NOT_CREATE_SRC_DIRECTORY

DO_NOT_CREATE_SERVICES_DIRECTORY

DO_NOT_CREATE_REPOSITORIES_DIRECTORY

DO_NOT_CREATE_CONTROLLERS_DIRECTORY

DO_NOT_CREATE_ADDITIONAL_TOP_LEVEL_DIRECTORIES

PREFER_EXISTING_DIRECTORIES_OVER_NEW_ONES

---

## FILE_PLACEMENT

api_routes -> app/api

request_schemas -> app/schemas

response_schemas -> app/schemas

shared_dependencies -> app/dependencies

application_configuration -> app/core

application_entry -> app/main.py

tests -> tests

---

## API_RULES

USE_APIRouter

GROUP_RELATED_ENDPOINTS

KEEP_ROUTE_MODULES_SMALL

KEEP_ENDPOINTS_FOCUSED

FOLLOW_FASTAPI_CONVENTIONS

ROUTES_BELONG_IN_APP_API

---

## SCHEMA_RULES

USE_PYDANTIC_MODELS

REQUEST_MODELS_ARE_REQUIRED

RESPONSE_MODELS_ARE_REQUIRED

SEPARATE_REQUEST_AND_RESPONSE_MODELS_WHEN_NEEDED

DO_NOT_USE_RAW_DICTIONARIES_FOR_PUBLIC_APIS

---

## DEPENDENCY_RULES

USE_FASTAPI_DEPENDENCY_INJECTION

SHARED_DEPENDENCIES_BELONG_IN_APP_DEPENDENCIES

AVOID_GLOBAL_STATE

PREFER_EXPLICIT_DEPENDENCIES

---

## CONFIGURATION_RULES

APPLICATION_CONFIGURATION_BELONGS_IN_APP_CORE

USE_ENVIRONMENT_VARIABLES_FOR_CONFIGURATION

DO_NOT_HARDCODE_SECRETS

DO_NOT_HARDCODE_CREDENTIALS

DO_NOT_HARDCODE_API_KEYS

---

## DATABASE_RULES

DATABASE_INTEGRATION_IS_OPTIONAL

DO_NOT_ASSUME_DATABASE_USAGE

DO_NOT_ASSUME_DATABASE_ENGINE

FOLLOW_DECLARED_PROJECT_DEPENDENCIES

---

## TESTING_RULES

TESTS_BELONG_IN_TESTS_DIRECTORY

USE_PYTEST

TEST_API_ENDPOINTS

TEST_CORE_BUSINESS_BEHAVIOR

---

## ARCHITECTURE_RULES

DO_NOT_CREATE_SERVICES_DIRECTORY

DO_NOT_CREATE_REPOSITORIES_DIRECTORY

DO_NOT_CREATE_CUSTOM_ARCHITECTURE

DO_NOT_INTRODUCE_PATTERNS_NOT_DEFINED_IN_ARCHITECTURE_MD

DO_NOT_CREATE_ABSTRACTIONS_WITHOUT_JUSTIFICATION

PREFER_SIMPLE_OVER_COMPLEX

---

## FORBIDDEN_DIRECTORIES

- src
- services
- repositories
- controllers

DO_NOT_CREATE_FORBIDDEN_DIRECTORIES

UNLESS_EXPLICITLY_REQUESTED

---

## ROOT_DIRECTORY_POLICY

ALLOWED_ROOT_DIRECTORIES

- app
- tests

ALLOWED_ROOT_FILES

- pyproject.toml
- README.md
- .env.example

DO_NOT_CREATE_UNDEFINED_ROOT_DIRECTORIES

---

## GENERATION_POLICY

BEFORE_CREATING_ANY_FILE

1. CHECK_EXISTING_STRUCTURE
2. CHECK_EXISTING_PATTERNS
3. REUSE_BEFORE_CREATING

PREFER_MODIFICATION_OVER_CREATION

DO_NOT_INVENT_ARCHITECTURE

DO_NOT_DUPLICATE_EXISTING_FUNCTIONALITY

PYPROJECT_TOML_OVERRIDES_VERSION_ASSUMPTIONS

WHEN_UNCERTAIN

FOLLOW_EXISTING_CODEBASE

DO_NOT_GUESS

---

## FASTAPI_PRINCIPLES

LATEST_STABLE_ONLY

NEW_PROJECTS_ONLY

API_FIRST

MINIMAL_STRUCTURE

SCHEMAS_ARE_REQUIRED

DEPENDENCY_INJECTION_OVER_GLOBAL_STATE

NO_ARCHITECTURAL_GUESSING

REUSE_BEFORE_CREATING

KEEP_IT_SIMPLE