IARA — Fisheries Inspection & Regulation Authority

A Flask web application for managing the full lifecycle of fisheries regulation: vessel registry, fishing permits, inspections & violations, angler tickets, QR verification, interactive maps, dashboards, alerts, and printable documents.

Project structure

.
├── run.py                  # Application entry point
├── requirements.txt        # Python dependencies
├── docs/                   # Project documentation
│   └── handoff.md
├── scripts/                # One-off / dev scripts (run from project root)
│   ├── seed_demo_data.py   # Large realistic demo dataset
│   ├── seed_lookup.py      # Species & gear-type reference data
│   ├── seed_ports.py       # Black Sea / Danube ports
│   ├── seed_violations.py  # Violation categories & codes
│   └── verify_app.py       # Smoke check: routes / templates / url_for / icons
├── migrations/             # Alembic database migrations
├── instance/               # SQLite database (git-ignored)
└── iara_app/               # Application package
    ├── __init__.py         # Application factory (create_app)
    ├── extensions.py       # Flask extension singletons (db, login, csrf, …)
    ├── config.py           # Configuration (env-overridable)
    ├── models.py           # SQLAlchemy models
    ├── forms.py            # WTForms form definitions
    ├── decorators.py       # Role / permission route guards
    ├── utils.py            # Shared helpers (audit log, rate limiting)
    ├── routes/             # Blueprints (HTTP layer)
    ├── services/           # Business logic & integrations
    │   ├── mail_service.py         alerts_service.py     gamification_service.py
    │   ├── permit_service.py       print_service.py      qr_service.py
    │   ├── qr_crypto.py            reports_service.py     weather_service.py
    ├── static/             # CSS, JS, images, service worker
    └── templates/          # Jinja2 templates

Setup

python -m venv .venv
.venv/Scripts/python -m pip install -r requirements.txt        # Windows
# source .venv/bin/activate && pip install -r requirements.txt # macOS/Linux

# Apply database migrations
FLASK_APP=run.py .venv/Scripts/python -m flask db upgrade

# (Optional) load reference + demo data
.venv/Scripts/python scripts/seed_lookup.py
.venv/Scripts/python scripts/seed_ports.py
.venv/Scripts/python scripts/seed_demo_data.py

Run

.venv/Scripts/python run.py        # http://127.0.0.1:5000

Demo accounts created by seed_demo_data.py use the password Demo1234! (e.g. g.kolev@iara-demo.bg — fisherman, m.koleva@iara-demo.bg — inspector).

Configuration

All settings are environment-overridable (see iara_app/config.py). Notable ones:

Variable	Purpose
SECRET_KEY	Session / CSRF signing key
DATABASE_URL	SQLAlchemy database URI (defaults to SQLite)
MAIL_SERVER, MAIL_USERNAME, MAIL_PASSWORD	SMTP (falls back to console output if unset)
OPENWEATHER_API_KEY	Live weather (falls back to demo data if unset)
QR_SECRET	AES key for encrypted QR payloads

Verify

After changes, run the project smoke check:

.venv/Scripts/python scripts/verify_app.py