Add Starlette Admin interface for Location management (MS Access replacement)

[kbighorse]

Summary

This PR implements a web-based admin interface to replace MS Access for managing Location records during the AMPAPI → NMSampleLocations migration.

Key Features:

• 🔐 Authentication: Integrates with existing Authentik OIDC auth
• 📋 List View: MS Access Datasheet-style grid with sorting, filtering, search
• ✏️ Forms: Create/edit forms with WKT coordinate input
• 🔒 RBAC: Admin/Editor/Viewer permissions
• 📊 Export: CSV and Excel export (like MS Access export)
• ⚡ Bulk Actions: Publish/unpublish selected locations
• 🗺️ WKT Field: Custom field handler for PostGIS geometry

---

Context: MS Access → Starlette Admin Migration

Staff are accustomed to using MS Access to manage the AMPAPI SQL Server database. This PR provides equivalent functionality in a web-based interface.

What Staff Are Gaining

✅ Multi-user access - No more "database is locked" errors
✅ Remote access - Work from anywhere (no VPN/RDP required)
✅ No file corruption - PostgreSQL is more robust than .accdb files
✅ Better security - User-level permissions vs. file permissions
✅ Audit trail - Track who changed what when
✅ Cross-platform - Works on Mac/Linux/iPad, not just Windows

What Staff Are Losing

❌ Offline access - Requires internet connection
⚠️ Complex queries - Use filters instead of Access query designer
⚠️ Custom reports - Export to CSV → Excel instead

---

AMPAPI → NMSampleLocations Schema Changes

Primary Key: GUID → Auto-Increment Integer

AMPAPI (SQL Server):

LocationId = Column(UNIQUEIDENTIFIER, primary_key=True)

NMSampleLocations (PostgreSQL):

id: Mapped[int]  # Auto-increment primary key
nma_pk_location: Mapped[UUID]  # Legacy GUID preserved for traceability

Coordinates: UTM → WGS84 Point Geometry

AMPAPI stored UTM Zone 12N/13N coordinates in separate fields:

Easting: 385000
Northing: 3900000
UTMZone: 13

NMSampleLocations stores WGS84 coordinates as PostGIS POINT:

point: POINT(-106.123 35.456)  -- WGS84 (SRID 4326)

For Staff: Instead of entering Easting/Northing/UTM Zone, enter:

POINT(-106.123 35.456)

Note: Longitude first, then latitude (not lat/lon!)

Release Status: Boolean → Lexicon Term

AMPAPI:

PublicRelease = Column(Boolean)  # True/False
Confidential = Column(Boolean)   # True/False

NMSampleLocations:

release_status: Mapped[str]  # 'draft', 'published', 'archived', etc.

Migration Mapping:

• PublicRelease=True → release_status='published'
• PublicRelease=False → release_status='draft'

Elevation: Feet → Meters

AMPAPI:

Altitude = Column(Float)  # Feet above sea level

NMSampleLocations:

elevation: Mapped[float]  # Meters (NAVD88 vertical datum)

Conversion: Feet → meters during migration

Site Type & PointID: Moved to Thing Table

AMPAPI stored PointID and SiteType in Location table.

NMSampleLocations moved these to Thing table:

• Location can have multiple things (wells, springs)
• PointID is thing-specific, not location-specific
• Many-to-many relationship via LocationThingAssociation

---

Admin Interface Details

List View (MS Access Datasheet Equivalent)

Columns Displayed:

• Location ID
• Description
• County
• State
• Elevation (meters)
• Quad Name
• Release Status
• Created At
• Updated By

Filters:

• County (dropdown)
• State (dropdown)
• Release Status (dropdown)
• Elevation (range)
• Created At (date range)

Search:

• Description
• County
• State
• Quad Name

Actions:

• Export to CSV
• Export to Excel
• Publish selected locations
• Unpublish selected locations

Form View (MS Access Form Equivalent)

Fields:

1. Description - Brief description
2. Coordinates (WKT) - Format: POINT(lon lat)
   • Help text explains conversion from UTM
   • Validates WKT format
3. Elevation - Meters (NAVD88)
4. County - New Mexico county
5. State - Default: "New Mexico"
6. Quad Name - USGS quadrangle
7. Location Notes - General notes
8. Coordinate Notes - Coordinate source/accuracy
9. Release Status - draft/published

Read-Only Fields (migration data):

• AMPAPI Location ID (legacy GUID)
• AMPAPI Date Created
• AMPAPI Site Date

Permissions

Role	Create	Edit	Delete	View
Admin	✅	✅	✅	All records
Editor	✅	✅	❌	All records
Viewer	❌	❌	❌	Published only

---

Implementation Details

Files Added

• admin/__init__.py - Package initialization
• admin/auth.py - Authentik OIDC authentication provider
• admin/config.py - Admin configuration
• admin/fields.py - Custom WKT field for PostGIS geometry
• admin/views.py - LocationAdmin view

Files Modified

• main.py - Mount admin at /admin
• pyproject.toml - Add starlette-admin dependency
• uv.lock - Update lock file

Testing Checklist

• Can access /admin (redirects to login if not authenticated)
• Login redirects to Authentik OIDC flow
• Location list displays with correct columns
• Search works (description, county, state)
• Filters work (county, state, release_status)
• Sorting works (click column headers)
• Admin can create location
• Editor can edit location
• Viewer cannot create/edit/delete
• WKT field accepts POINT(-106.123 35.456)
• Bulk publish action works
• Export to CSV works
• Viewer sees only published locations

---

Next Steps

After this PR:

1. ✅ Local testing - Test with development database
2. ✅ User acceptance testing - Demo to 2-3 staff members
3. ✅ User guide - Create documentation for staff
4. ✅ Training - 1-hour session for staff
5. ⏭️ Add more models - Thing, Sample, Observation, etc.

---

Related Documentation

• AMPAPI Location model: /AMPAPI/models/location.py
• NMSampleLocations Location model: /NMSampleLocations/db/location.py
• Starlette Admin docs: https://jowilf.github.io/starlette-admin/

[Copilot]

Pull request overview

This PR implements a web-based Starlette Admin interface to replace MS Access for managing Location records during the AMPAPI → NMSampleLocations migration. The interface integrates with existing Authentik OIDC authentication and provides familiar MS Access-like functionality including list views, forms, filtering, and bulk operations.

Key Changes:

• Added Starlette Admin dependency for web-based database management
• Implemented OIDC authentication integration with Authentik
• Created Location admin view with RBAC permissions (Admin/Editor/Viewer roles)

Reviewed changes

Copilot reviewed 7 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
pyproject.toml	Added starlette-admin[i18n] dependency for admin interface functionality
main.py	Mounted admin interface at /admin route
admin/init.py	Package initialization exporting create_admin function
admin/config.py	Admin configuration with Location view registration
admin/auth.py	Authentik OIDC authentication provider with role mapping
admin/fields.py	Custom WKT field handlers for PostGIS geometry columns
admin/views.py	Location model admin view with list/form/permission configuration

[Copilot]

The docstring states "Only admins can create new locations" but according to the PR description's permission table, both Admins and Editors should have create permissions. Either update the docstring to match the actual permission model or update the implementation to allow editors to create locations.

Suggested change

	Only admins can create new locations.
	Returns:
	bool: True if user has 'admin' role
	"""
	user = getattr(request.state, "user", None)
	if user is None:
	return False
	return "admin" in getattr(user, "roles", [])
	Admins and editors can create new locations.
	Returns:
	bool: True if user has 'admin' or 'editor' role
	"""
	user = getattr(request.state, "user", None)
	if user is None:
	return False
	roles = getattr(user, "roles", [])
	return "admin" in roles or "editor" in roles

[Copilot]

Pull request overview

Copilot reviewed 10 out of 11 changed files in this pull request and generated 2 comments.

[Copilot]

The test expectation shows Editor can delete ('should' in can_delete column), but according to the permission table in the PR description and the can_delete implementation in admin/views.py, Editors should not be able to delete. This test data appears incorrect.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[jirhiker]

There is a lot to discuss regarding this PR. First this concept is/was being explored via fastapi-admin. Second ocotillo has this "admin" functionality. Third, user research and experience have repeatedly revealed and reinforced that users do not want single table interfaces- this was a major complaint when users used NMAQuiferDev. Lastly, given that end users will not use it, and developers already have clients available for database management, who is the audience for this functionality? Developing a consensus around this will be important moving forward

[kbighorse]

@jirhiker Yes, this is part of a proposal we will bring to you very shortly. More to come.

[jirhiker]

There is considerable potential for this approach, and this appears to be a well-designed and clean implementation. However, the issue we have always run into is that ultimately we find ourselves having to write a ton of custom JS to implement the functionality the users (or even admins) really want (Perhaps this is more a function of NMAquifers' poor data model than an issue with the monolithic approach). The need for a bunch of custom JS/CSS/HTML has led us to move all Web GUI development to JS/React applications. The need for responsive, user-friendly, modern UIs eventually supersedes the benefits of a monolithic server-side application. So if there are clear guardrails on what the Admin UI is for and who should know about it/use it then I think this could be made a priority

[kbighorse]

does MS Access support such functionality?

[jirhiker]

I'm not sure which functionality you are referring to. However, I don't think that using ms access/ampapi as a baseline is valuable in this case. Limiting ourselves to what ms access did even temporarily does not seem a worthwhile goal. The previous workflow for data entry via ms access and nmaquiiferdev were highly compromised and bespoke because of both technical and culture issues. The Ms access-centric view also neglects the fact that a significant number of users interact with our data entirely independently of Ms access. Only a small number of users enter data (2-3) via Ms access, a slightly larger group may have used Ms access to view data, however the majority of users worked with our data either via the "interactive web map" or with arcgis via data exports (only a few users were capable and confident enough to us Ms access to generate data exports)

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[jirhiker]

Right now there is a lot of duplicated code in the ModelView subclasses. It would be great to consolidate functionality into a OcotilloModelView subclass. The duplicated code im referring to is stuff like this

#========== Permissions (RBAC) ==========

    def can_create(self, request: Request) -> bool:
        user = getattr(request.state, "user", None)
        if user is None:
            return False
        return "admin" in getattr(user, "roles", [])

    def can_edit(self, request: Request) -> bool:
        user = getattr(request.state, "user", None)
        if user is None:
            return False
        roles = getattr(user, "roles", [])
        return "admin" in roles or "editor" in roles

    def can_delete(self, request: Request) -> bool:
        user = getattr(request.state, "user", None)
        if user is None:
            return False
        return "admin" in getattr(user, "roles", [])

    def can_view_details(self, request: Request) -> bool:
        user = getattr(request.state, "user", None)
        return user is not None

    # ========== Data Visibility (Release Status Filter) ==========

    async def get_list_query(self, request: Request):
        query = select(self.model)

        user = getattr(request.state, "user", None)
        if user is None:
            return query.where(self.model.id == -1)

        roles = getattr(user, "roles", [])
        if "admin" in roles or "editor" in roles:
            return query
        else:
            return query.where(self.model.release_status == "published")

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.