Atlantic Technological University (ATU)

PROJ_IT805 - LY_ICSWD_B: Project (2025/26)

Supervisors: Pauric Dawson, Lusungu Mwase

---

Pokédex Image Recognition System

Student: Edson Ferreira — L00196839

🌐 Live: pocketmonsters.fun

A web-based system that identifies Pokémon from a photo. Upload an image or take a photo with your camera — the system recognises the Pokémon and returns its name, type, and stats.

---

Table of Contents

1. Overview
2. Getting Started
3. Repository Structure
4. Technology Stack
5. Architecture
6. API
7. Testing
8. CI/CD Pipeline
9. Contributing
10. Documentation
11. License

---

1. Overview

The Pokédex Image Recognition System allows users to:

• Upload a photo or take one with their camera
• Identify the Pokémon in the image using YOLO object recognition
• View the Pokémon's name, type(s), and base stats
• Experience a Pokédex-styled responsive web interface

Versioning

Version	Description	Status
PoC	YOLO cat recognition from local file	✅ Done
MVP	FastAPI + YOLO, end-to-end via HTTP	✅ Done
V1	Pokémon model + web UI	✅ Done
V2	Pokédex-styled UI + deployed to AWS	✅ Done

---

2. Getting Started

Prerequisites

• Python 3.11+
• uv (recommended) or pip
• Docker (optional, for deployment and GitHub MCP server)

Quick Setup (first time)

git clone https://github.com/edsonesf/ATU-CSD-POKEDEX.git
cd ATU-CSD-POKEDEX
./scripts/setup.sh

This creates .env (chmod 600), installs dependencies, sets up pre-commit hooks, and runs quality checks.

Manual Setup

# Install dependencies
uv sync                    # or: pip install -e ".[dev]"

# Configure environment
cp .env.example .env && chmod 600 .env
# Edit .env with your tokens (see .env.example for details)

# Seed the database (required on first run)
PYTHONPATH=src python scripts/seed_db.py

# Start the server
PYTHONPATH=src uvicorn app.main:app --reload

• API: http://localhost:8000
• Interactive docs: http://localhost:8000/docs
• OpenAPI spec: http://localhost:8000/openapi.json

Run with Docker

docker build -t pokedex .
docker run -p 8000:8000 pokedex

AI Agent Setup

This repo includes workspace configs for Kiro CLI and Gemini CLI:

# Kiro CLI (swap to dev agent)
kiro-cli --agent dev

# Gemini CLI (auto-discovers .gemini/settings.json)
gemini

Agents require GITHUB_PERSONAL_ACCESS_TOKEN in your environment. See ADR-031 for the full secrets strategy.

---

3. Repository Structure

This is a multi-concern monorepo. The FastAPI application lives under src/app/ to keep it isolated from infrastructure, ML, and tooling directories (see ADR-020).

ATU-CSD-POKEDEX/
├── src/
│   └── app/              # FastAPI application (Python package)
│       ├── main.py       # App entry point, /health endpoint
│       ├── api/          # HTTP route handlers (thin layer)
│       ├── services/     # Business logic
│       ├── models/       # SQLAlchemy ORM models
│       ├── schemas/      # Pydantic request/response models
│       ├── repositories/ # Database access layer
│       └── core/         # Config, settings, shared utilities
├── tests/                # Test suite (mirrors src/app/ structure)
├── poc/                  # YOLO proof-of-concept scripts
├── docs/                 # Architecture, ADRs, API docs, diagrams
├── scripts/              # DB seeding, data fetch utilities
├── infra/              # Terraform infrastructure (AWS)
├── ml/                   # Future: model training pipelines
├── academic/             # University chapters and research
├── requirements.txt      # Production: web/db deps (FastAPI, SQLAlchemy, etc.)
├── requirements-cv.txt   # Computer vision: ultralytics/YOLO, Pillow
├── requirements-dev.txt  # Dev: -r requirements.txt + -r requirements-cv.txt + dev tools
├── requirements-ci.txt   # CI: -r requirements.txt + dev tools (no ultralytics)
├── pyproject.toml        # Tool config (pytest, ruff, mypy)
└── Dockerfile

Why src/app/ and not app/ at root? Setting PYTHONPATH=src means all imports stay as app.services.X, app.api.X — consistent with the architecture docs and ADRs. The src/ wrapper keeps the root clean as infra/ and ml/ directories are added. See ADR-020 in docs/design-decisions.md.

---

4. Technology Stack

Backend

• Python 3 + FastAPI — REST API
• YOLO (Ultralytics/YOLOv8) — image recognition
• SQLAlchemy — ORM
• SQLite (dev) / PostgreSQL (production) — see ADR-006

Frontend

• HTML, CSS, JavaScript — responsive web UI
• Camera capture via browser getUserMedia API

DevOps

• Terraform — Infrastructure as Code (IaC)
• Docker — containerisation
• GitHub Actions — CI/CD pipeline (SHA-pinned)
• AWS ECR — container registry
• AWS ECS Fargate — serverless container hosting
• ECS Express Mode — canary deployment with automatic rollback (ADR-032)

Code Quality

• ruff — Python linting + formatting
• mypy — Python type checking
• pytest — Python testing
• TFLint + Checkov — IaC linting and security scanning
• pre-commit — git hooks (ruff + mypy + pytest + terraform)

---

5. Architecture

The backend follows a layered architecture with a shared domain model:

• HTTP Layer — FastAPI routes (POST /identify, GET /health)
• Service Layer — IdentificationService (orchestration), RecognitionService (YOLO inference)
• Repository Layer — PokemonRepository (SQLAlchemy DB access)
• Persistence Layer — PokemonModel (ORM) + Database (SQLite dev / PostgreSQL prod)
• Domain Model — Pokemon, RecognitionResult, IdentifyResponse (shared data classes, not a call-chain layer)

For full architecture details, diagrams, and ADRs see docs/architecture.md.

---

6. API

Method	Endpoint	Description
GET	/health	Liveness probe
GET	/api/v1/health	Health check with model status
POST	/api/v1/identify	Upload image → identify Pokémon
GET	/api/v1/pokemon	List Pokémon (paginated, searchable)
GET	/api/v1/pokemon/{id}	Get single Pokémon by ID

Full API specification: docs/api.md | Interactive docs: http://localhost:8000/docs

---

7. Testing

PYTHONPATH=src pytest -v              # run all tests
PYTHONPATH=src pytest --cov=app       # with coverage report

Code quality checks

PYTHONPATH=src ruff check .           # linting
PYTHONPATH=src ruff format --check .  # formatting
PYTHONPATH=src mypy src/app/          # type checking

All checks must pass before merging to main. See ADR-029 for testing strategy.

---

8. CI/CD Pipeline

Every push triggers:

1. ruff lint + format checks, mypy type checking
2. pytest test suite with coverage enforcement
3. Security scanning: Semgrep (SAST), pip-audit (SCA), Gitleaks (secrets)
4. Terraform Quality Gates: fmt, validate, TFLint, Checkov, and test (on infra/ changes)
5. Opt-in (label-triggered): Trivy container scan, Schemathesis DAST, Docker smoke test
6. Push to AWS ECR (on merge to main)
7. Canary deployment to ECS Fargate via Express Mode (ADR-032)

Automatic rollback on health-check failure.

---

9. Contributing

1. Pick an issue from the project board
2. Create a branch: git checkout -b feature/description
3. Write tests first (TDD)
4. Implement the feature
5. Run all checks locally before pushing
6. Open a Pull Request using the PR template
7. Merge after CI passes

Branch protection is enabled — no direct pushes to main.

---

10. Documentation

Document	Description
Project Plan	Milestones, Epics, Issues
Design Decisions	Architecture Decision Records (ADRs)
Architecture	System architecture and UML diagrams
API Design	REST API specification and response models
User Stories	User stories and acceptance criteria
CI/CD	Pipeline design and deployment strategy
SKILL.md	Agent skills index — task-specific instructions for AI agents
AGENTS.md	AI agent configuration and project conventions

Agent Skills

AI coding agents (Kiro, Antigravity, Gemini CLI) use skills from .agents/skills/ for consistent workflows. See SKILL.md for the full index.

---

11. License

This project is licensed under the MIT License — see the LICENSE file for details.

Third-party Licenses

• YOLOv8 (Ultralytics): The YOLOv8 model and associated Ultralytics library are licensed under the AGPL-3.0 License. Note that this applies to the redistribution of the model and library, not to the application code in this repository.

Disclaimer

This is a university project created for educational purposes. Pokémon and Pokémon character names are trademarks of Nintendo, Game Freak, and The Pokémon Company. This project is not affiliated with, sponsored by, or endorsed by Nintendo, Game Freak, or The Pokémon Company.