Bird Tagging System

Bird Tagging System is a Streamlit and AWS application for uploading bird media, detecting likely bird species, organizing files with tags, and searching the resulting collection.

It combines a Python Streamlit front end with AWS Cognito, S3, Lambda, API Gateway, DynamoDB, SNS, thumbnail generation, and bird-classification Lambda functions. The repository is useful for learning how a media-management app can connect authenticated users, serverless file processing, and machine-learning based tagging.

Jump To

• What It Does
• Architecture
• Repository Layout
• Getting Started
• AWS Configuration Boundary
• Validation
• Roadmap
• Contributing

What It Does

• Authenticates users with AWS Cognito.
• Uploads images, videos, and audio files through a Streamlit interface.
• Stores uploaded media in Amazon S3.
• Runs serverless processing through AWS Lambda.
• Generates thumbnails for uploaded media.
• Applies automated bird-species tags using packaged model assets.
• Lets users search by species, tags, file URL, or uploaded reference file.
• Supports bulk tag management and file deletion workflows.
• Sends email notifications for subscribed bird tags through AWS SNS.

Architecture

Streamlit UI
  -> AWS Cognito for authentication
  -> API Gateway endpoints
  -> Lambda handlers for upload, query, tagging, delete, subscribe, thumbnails
  -> S3 buckets for media and generated thumbnails
  -> DynamoDB metadata tables
  -> SNS notifications for subscription alerts

The app is designed around AWS-managed services. The Streamlit app is the user-facing control surface; Lambda handlers own file processing, search, thumbnail, and notification workflows; S3 and DynamoDB hold media and metadata.

Repository Layout

.
|-- streamlit_app.py          # Authenticated Streamlit landing page
|-- pages/                    # Upload, search, delete, tag, and subscribe pages
|-- helpers.py                # Shared Streamlit/API helpers
|-- auth.py                   # Cognito sign-in/session handling
|-- config.py                 # Environment-specific AWS endpoint/resource config
|-- lambda/                   # Lambda functions and container build contexts
|-- css/                      # Streamlit styling
|-- requirements.txt          # Streamlit app dependencies

Notable Lambda areas:

• lambda/upload/ handles upload flow integration.
• lambda/birdTagLambda/ packages model-backed bird tagging.
• lambda/birdNET/ contains a BirdNET-oriented Lambda container.
• lambda/thumbnails/ generates media thumbnails.
• lambda/*QueryHandler/ serves metadata and search queries.
• lambda/subscribe/ and lambda/notifySubscribers/ power tag subscriptions.

Getting Started

Prerequisites

• Python 3.11 or newer.
• An AWS account with permission to create or use Cognito, S3, Lambda, API Gateway, DynamoDB, and SNS resources.
• AWS credentials configured locally if you need to deploy or test AWS-backed paths.

Install

git clone https://github.com/RayLi-Muye/bird_detection.git
cd bird_detection
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run the Streamlit App

streamlit run streamlit_app.py

By default the application expects valid AWS Cognito and API Gateway settings in config.py. Local UI startup is useful for development, but authenticated end-to-end behavior requires a matching AWS deployment.

AWS Configuration Boundary

The repository includes environment-specific identifiers in config.py, such as region, Cognito app metadata, bucket name, redirect URI, and API base URL. Treat those values as deployment configuration, not reusable credentials.

For your own deployment:

• Create your own Cognito user pool and app client.
• Create your own S3 buckets and DynamoDB tables.
• Deploy the Lambda handlers and API Gateway routes.
• Update config.py or refactor it to load from environment variables.
• Never commit AWS secret keys, access tokens, private certificates, or production-only credentials.

The checked-in Lambda folders include source files, Dockerfiles, requirements, model assets, and labels needed by the application code. They do not create AWS infrastructure by themselves.

Validation

For documentation-only changes:

git diff --check

For a basic Python syntax pass:

python -m compileall streamlit_app.py helpers.py auth.py config.py pages lambda

For UI work, run Streamlit locally and exercise the affected page. For AWS-backed behavior, validate against a non-production AWS environment with test media and test user accounts.

Roadmap

• Document the exact AWS infrastructure setup and IAM permissions.
• Move environment-specific config toward environment variables or a sample config template.
• Add deployment scripts or infrastructure-as-code for repeatable setup.
• Add automated tests for helper functions and Lambda handlers.
• Add smoke-test documentation for upload, search, tag management, and subscriptions.
• Improve local development paths that do not require production AWS resources.

Contributing

Use the GitHub-native workflow:

1. Open or link an issue describing the problem, scope, validation plan, risk, and rollback.
2. Work on a topic branch.
3. Open a pull request that links the issue.
4. Include validation evidence, docs impact, and any AWS boundary notes.
5. Avoid committing credentials, generated caches, local virtual environments, or build outputs.

Security

Do not upload secrets or production-only credentials to this repository. Use least-privilege AWS IAM roles for Lambda and Streamlit-hosted access. Validate destructive operations, such as file deletion, against test data before using them in a shared or production environment.

Resources

• Streamlit documentation
• AWS Lambda documentation
• Amazon Cognito documentation
• Amazon S3 documentation
• Amazon DynamoDB documentation
• Amazon SNS documentation