# AniWorld Project Overview

## 📁 Folder Structure

The project follows a modular, layered architecture inspired by MVC and Clean Architecture principles. The main directories are:

```
src/
  controllers/    # API endpoints and route handlers
  services/       # Business logic and orchestration
  repositories/   # Data access layer (DB, external APIs)
  schemas/        # Pydantic models for validation/serialization
  utils/          # Utility functions and helpers
  config/         # Configuration management (env, settings)
tests/
  unit/           # Unit tests for core logic
  integration/    # Integration tests for end-to-end scenarios
```

## 🏗️ Architecture

- **MVC & Clean Architecture:** Separation of concerns between controllers (views), services (business logic), and repositories (data access).
- **Dependency Injection:** Used for service/repository wiring, especially with FastAPI's `Depends`.
- **Event-Driven & Microservices Ready:** Modular design allows for future scaling into microservices or event-driven workflows.
- **Centralized Error Handling:** Custom exceptions and error middleware for consistent API responses.

## 🧰 Used Libraries & Frameworks

- **Python** (PEP8, PEP257, type hints)
- **FastAPI**: High-performance async web API framework
- **Pydantic**: Data validation and serialization
- **Poetry**: Dependency management and packaging
- **dotenv / os.environ**: Environment variable management
- **logging / structlog**: Structured logging
- **pytest / unittest**: Testing frameworks
- **aiohttp**: Async HTTP client (where needed)
- **SQLAlchemy / asyncpg / databases**: Database ORM and async drivers (if present)
- **Prometheus**: Metrics endpoint integration
- **Other**: As required for integrations (webhooks, third-party APIs)

## 🧩 Patterns & Conventions

- **Repository Pattern:** All data access is abstracted via repositories.
- **Service Layer:** Business logic is encapsulated in services, not controllers.
- **Pydantic Models:** Used for all input/output validation.
- **Async Endpoints:** All I/O-bound endpoints are async for scalability.
- **Environment Configuration:** All secrets/configs are loaded from `.env` or environment variables.
- **Logging:** All logs are structured and configurable.
- **Testing:** High coverage with fixtures and mocks for external dependencies.

## 🛡️ Security & Performance

- **JWT Authentication:** Secure endpoints with token-based auth.
- **Input Validation:** All user input is validated via Pydantic.
- **No Hardcoded Secrets:** All sensitive data is externalized.
- **Performance Optimization:** Async I/O, caching, and profiling tools.

## 🎨 UI & CLI

- **Theme Support:** Light/dark/auto modes.
- **Accessibility:** Screen reader, color contrast, keyboard shortcuts.
- **CLI Tool:** For bulk operations, scanning, and management.

## 📚 References

- [FastAPI Documentation](https://fastapi.tiangolo.com/)
- [Pydantic Documentation](https://docs.pydantic.dev/)
- [Poetry](https://python-poetry.org/docs/)
- [PEP 8](https://peps.python.org/pep-0008/)
- [Black Formatter](https://black.readthedocs.io/)

---

**For details on individual features and endpoints, see `features.md`.**