OceanGuard

OceanGuard is a Flask web application focused on marine conservation, wildlife observation, and community participation.

It combines a species explorer, conservation project pages, observation mapping, and a social community space in one project. The goal is to make marine biodiversity feel more visible, more human, and easier to engage with through the web.

Preview

OceanGuard is designed to feel immersive and approachable: a story-led homepage, rich species pages, community features, and conservation content all in one experience.

Why This Project Matters

Ocean ecosystems are under pressure from habitat loss, pollution, overfishing, and climate change. OceanGuard is designed as a digital space where users can:

• discover threatened marine species
• learn about conservation work already happening
• record and explore observations on a map
• share questions, updates, and knowledge with a community

This makes the project a good fit for people interested in climate tech, environmental education, civic technology, accessibility, and open-source web development.

What You Can Do In OceanGuard

• Browse a marine species directory with conservation status, threats, habitat, and supporting details
• Open rich species detail pages and track species you care about
• Explore conservation projects and project-specific species links
• Add wildlife observations with map coordinates and contextual notes
• View community-submitted observations on an interactive map
• Join a community feed with posts, comments, likes, and bookmarks
• Use profile pages, activity signals, and lightweight gamification to encourage participation
• Moderate the platform with admin tools for projects, users, and observation verification

Why Contributors Might Enjoy It

OceanGuard is a strong contribution-friendly project because it sits at the intersection of multiple interesting areas:

• Flask application architecture
• SQLAlchemy models and relational data design
• UX and visual storytelling for environmental products
• accessibility and inclusive interface improvements
• search, recommendation, and community features
• data curation for science and education content

If you like projects that feel more meaningful than a generic CRUD app, this repo has a lot of room for improvement and experimentation.

Quick Start

OceanGuard runs as a local Flask app with SQLite, so you do not need to install a separate database server for development.

macOS

1. Create and activate a virtual environment:

python3 -m venv .venv
source .venv/bin/activate

2. Install dependencies:

python -m pip install -r requirements.txt

3. Create your local environment file:

cp .env.example .env

4. Update .env with your own values. To create a local admin account on first run, use:

OCEANGUARD_CREATE_ADMIN=true
OCEANGUARD_ADMIN_USERNAME=admin
OCEANGUARD_ADMIN_EMAIL=admin@example.com
OCEANGUARD_ADMIN_PASSWORD=your-own-strong-password

5. Start the application:

python app.py

6. If port 5000 is already in use on macOS, start on a different port:

PORT=5001 python app.py

7. Open the app in your browser:

http://127.0.0.1:5000

Or, if you used another port:

http://127.0.0.1:5001

Windows

1. Create and activate a virtual environment in PowerShell:

py -3 -m venv .venv
.venv\Scripts\Activate.ps1

If you are using Command Prompt instead:

py -3 -m venv .venv
.venv\Scripts\activate.bat

2. Install dependencies:

python -m pip install -r requirements.txt

3. Create your local environment file:

Copy-Item .env.example .env

4. Update .env with your own values. To create a local admin account on first run, use:

OCEANGUARD_CREATE_ADMIN=true
OCEANGUARD_ADMIN_USERNAME=admin
OCEANGUARD_ADMIN_EMAIL=admin@example.com
OCEANGUARD_ADMIN_PASSWORD=your-own-strong-password

5. Start the application:

python app.py

6. If port 5000 is already in use, start on a different port:

$env:PORT=5001
python app.py

7. Open the app in your browser:

http://127.0.0.1:5000

Or, if you used another port:

http://127.0.0.1:5001

Notes

• On first launch, OceanGuard creates the local SQLite database automatically.
• The app now supports the PORT environment variable, which is useful if port 5000 is occupied.
• On some macOS setups, 5000 may be used by AirPlay Receiver or other system services.

Environment Variables

• SECRET_KEY: Flask secret key used for session security
• OCEANGUARD_CREATE_ADMIN: Set to true to create a local admin during initialization
• OCEANGUARD_ADMIN_USERNAME: Admin username used during bootstrap
• OCEANGUARD_ADMIN_EMAIL: Admin email used during bootstrap
• OCEANGUARD_ADMIN_PASSWORD: Admin password used during bootstrap

Project Structure

.
├── app.py
├── data/
├── docs/
├── static/
├── templates/
├── .github/
└── requirements.txt

Current Stack

• Python
• Flask
• Flask-SQLAlchemy
• Flask-Login
• Flask-WTF
• SQLite
• HTML, CSS, and vanilla JavaScript

Areas Where Contributions Would Help Most

• Add automated tests for core routes, forms, and permissions
• Split the monolithic app.py into blueprints, services, and model modules
• Improve mobile responsiveness and accessibility across templates
• Add deployment instructions for Render, Railway, or Docker
• Improve observation validation and moderation workflows
• Expand marine species datasets and improve data quality tooling
• Add screenshots, GIF demos, and better visual documentation
• Introduce CI checks for formatting, linting, and tests

Good First Contribution Ideas

• Improve onboarding copy and empty states
• Add form validation feedback polish
• Refine search behavior and filter UX
• Add tests for login, registration, and community flows
• Clean up duplicate styles or template inconsistencies
• Improve README visuals and contributor docs

Roadmap

• Modularize the Flask application structure
• Add a production-ready deployment path
• Improve map exploration and filtering
• Expand recommendation and discovery features
• Strengthen admin moderation workflows
• Add more public-facing educational content around marine conservation

Open Source Readiness Notes

• Local databases, logs, caches, and .env files are ignored
• Sensitive hardcoded admin credentials were removed from the codebase and cleaned from reachable Git history
• Placeholder contact information in public-facing templates should still be reviewed before promotion or deployment

Community

• Contribution guide: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md

Issues and pull requests are welcome, especially around accessibility, testing, architecture, environmental storytelling, and contributor experience.

License

This project is released under the MIT License.