# EcoSpecies-Atlas

Modern open-source follow-on to the legacy EcoSpecies application, built to ingest historical Species Life History materials and evolve into a maintainable public research platform.

## Repository layout

- `apps/api`: Python API and import logic
- `apps/web`: public web UI served by nginx
- `docs`: migration survey and roadmap
- `scripts`: Compose runtime scripts for bootstrapping the container-managed Python environment
- Docker named volume `python_venv`: container-managed Python virtual environment
- Docker named volume `pip_cache`: pip cache for container bootstrapping
- Docker named volume `postgres_data`: PostgreSQL data directory
- `var/sqlite`: host fallback for local non-Compose verification

## Runtime model

Docker Compose owns all runtime dependencies:

- PostgreSQL runs in a container with a Docker-managed named volume
- Python services run in `python:3.12-slim`
- the Python virtual environment is created in a Docker-managed volume mounted at `/workspace/.docker/venv`
- dependencies are installed from `apps/api/requirements.txt` inside that virtual environment
- the legacy corpus is mounted read-only from `../01-legacy-code-and-data`

No host Python packages are required for the Compose workflow.

## Start the stack

```bash
cd EcoSpecies-Atlas
docker compose up
```

Endpoints:

- web UI: `http://localhost:8080`
- API: `http://localhost:8000`
- PostgreSQL: `localhost:5432`
- liveness: `/healthz`
- readiness: `/readyz`
- auth session: `/api/auth/session`
- editor status: `/api/editor/status` (requires `editor` or `admin`)
- editor species list: `/api/editor/species` (requires `editor` or `admin`)
- editor workflow detail/update: `/api/editor/species/<slug>/workflow` (requires `editor` or `admin`)
- editor species detail: `/api/editor/species/<slug>` (requires `editor` or `admin`)
- editor editorial update: `/api/editor/species/<slug>/editorial` (requires `editor` or `admin`)
- editor section detail/update: `/api/editor/species/<slug>/sections/<position>` (requires `editor` or `admin`)
- editor audit history: `/api/editor/species/<slug>/audit` (requires `editor` or `admin`)

If those host ports are already in use, override them when starting Compose, for example:

```bash
ECOSPECIES_API_PORT=18000 ECOSPECIES_WEB_PORT=18080 docker compose up
```

## Host-visible state

All important runtime state is bind-mounted and visible on the host:

- source code and docs in this repo
- SQLite fallback database in `var/sqlite`
- optional SQLite fallback in `var/sqlite`

## Automated checks

Repository-host CI runs the repository-layer tests and the stubbed browser smoke test on pushes and change requests.
Contributor workflow guidance is in `CONTRIBUTING.md`.

When hosted on Forgejo, the current GitHub-compatible workflow layout can still be used. Forgejo Actions will look for workflows in `.forgejo/workflows`, and if that directory is absent it will fall back to `.github/workflows`. A Forgejo-native template is provided at `.forgejo/workflows/ci.yml.template`; copy it to `.forgejo/workflows/ci.yml` only after adapting the runner label and action source policy for the target instance. The activation checklist is in `docs/forgejo-activation.md`.

Run the repository-layer test suite with:

```bash
./scripts/check-api-tests.sh
```

Run the browser-level editor smoke test with:

```bash
./scripts/check-ui-smoke.sh
```

Run the browser-level smoke test against the real Compose stack with:

```bash
./scripts/check-ui-stack-smoke.sh
```

## Notes

- The importer seeds PostgreSQL from the legacy text corpus before the API starts and now synchronizes by slug instead of truncating the full dataset.
- Species missing from a later import payload are archived instead of deleted. Public endpoints hide archived records; editor endpoints can still inspect them.
- The editor species list supports `active`, `all`, and `archived` client-side filtering so archived records remain manageable in the UI.
- Editors can also archive or unarchive species explicitly from the editorial controls, with audit history recorded alongside other editorial changes.
- The API also supports a host-local SQLite fallback for direct verification when `ECOSPECIES_DATABASE_URL` is unset.
- PostgreSQL, the Python virtualenv, and the pip cache use Docker named volumes because bind-mounted runtime state is not reliable on CIFS-backed workspaces like this one.
- Initial editor auth uses `ECOSPECIES_AUTH_TOKENS` in the format `token:username:role[,token2:username2:role2]`, where `role` is `viewer`, `editor`, or `admin`.
- Editorial workflow state is persisted per species with `draft`, `review`, and `published` statuses. Public endpoints return only `published` records; editor endpoints can inspect and update all records.
- Editors can curate top-level metadata and section content from the web UI, and every editorial or section change is recorded in per-species audit history.
- Summary authoring guidance for future FLELMR-compatible records is in `docs/flelmr-authoring.md`.
- Legacy survey and roadmap artifacts are in `docs/`.

## Governance And Operations

The repository host, such as GitHub or Forgejo, is used for source control, change requests, code review, and CI checks. It is not part of the application runtime.

EcoSpecies-Atlas itself runs through Docker Compose, the Python API, nginx, and PostgreSQL. Import jobs, editor workflows, and browser access all depend on the application stack, not on the repository host.

In practice, the repository host is responsible for change management:

- storing the code, docs, workflow definitions, and test harnesses
- running CI checks on pushes and change requests
- supporting review and merge workflows

In practice, the application stack is responsible for operations:

- serving the web UI and API
- persisting editorial and import state
- running imports and editor workflows