feat: implement PostGIS table discovery API (#57)

[mikemcdougall]

Summary

Implements Issue #57: PostGIS table discovery feature that allows users to discover and list all spatial tables in a PostGIS database.

Changes

• ✨ New API Endpoint: GET /api/admin/connections/{id}/tables
• 🗄️ PostgreSQL Table Discovery: Queries geometry_columns and geography_columns system views
• 📊 Rich Metadata: Returns table schema, name, geometry column info, SRID, estimated row count, and all non-geometry columns
• 🧪 Integration Tests: Comprehensive test suite with AOT-compatible JSON serialization
• 📝 Source-Generated Logging: High-performance logging for AOT compatibility
• 🏗️ Feature Organization: Follows greenfield project patterns with proper separation of concerns

API Response Format

{
  "tables": [
    {
      "schema": "public",
      "table": "parcels",
      "geometryColumn": "geom", 
      "geometryType": "MULTIPOLYGON",
      "srid": 4326,
      "estimatedRows": 50000,
      "columns": [
        {
          "name": "id",
          "dataType": "integer",
          "isNullable": false,
          "isPrimaryKey": true
        }
      ]
    }
  ]
}

Technical Implementation

• AOT Compatible: Full native AOT compilation support with source-generated JSON serialization
• Performance Optimized: Uses parameterized queries and column indexes for efficiency
• Error Handling: Comprehensive error handling with proper HTTP status codes
• Security: Excludes system schemas and uses safe query patterns
• Testing: Integration tests with proper test attributes for categorization

Verification Steps

• ✅ Builds successfully in Debug mode
• ✅ AOT publish succeeds without warnings
• ✅ dotnet format applied and clean
• ✅ Integration tests pass
• ✅ Follows project architectural patterns
• ✅ Implements exact API specified in issue

Closes #57

🤖 Generated with Claude Code

Co-Authored-By: Claude Sonnet 4 [email protected]

[github-actions]

🤖 LLM Architecture Review

✅ Assessment: APPROVED

🏗️ Architecture Review Summary

✅ Good Patterns Found:

• Use of Minimal APIs in AdminEndpoints.cs aligns with the architectural requirement for lightweight, focused endpoints (src/Honua.Server/Features/Admin/AdminEndpoints.cs:10).
• Dependency injection is correctly used to manage services like ITableDiscoveryService, promoting loose coupling and testability (src/Honua.Server/Program.cs:71).
• Proper use of asynchronous programming patterns in endpoint handlers ensures scalability and efficient resource use (src/Honua.Server/Features/Admin/AdminEndpoints.cs:44).

⚠️ Architecture Concerns:

• Critical: Dependency inversion violation with the Core layer depending on Infrastructure, seen in AdminEndpoints.cs where IDatabaseConnectionProvider is directly used (src/Honua.Server/Features/Admin/AdminEndpoints.cs:75). This should be abstracted through interfaces defined in the Core layer.
• Warning: The PostgreSqlTableDiscoveryService class is tightly coupled to PostgreSQL, which may limit flexibility if database technologies are changed in the future (src/Honua.Server/Features/Admin/Services/PostgreSqlTableDiscoveryService.cs:10).
• Warning: Synchronous operations found in GetEstimatedRowCountAsync and GetTableColumnsAsync methods which might block threads under high load (src/Honua.Server/Features/Admin/Services/PostgreSqlTableDiscoveryService.cs:248, 287).

💡 Recommendations:

• Refactor the PostgreSqlTableDiscoveryService to use an interface that abstracts database operations, allowing for easier swapping of database technologies:

  public interface IDatabaseService {
      Task<List<TableInfo>> ExecuteQueryAsync(string query, CancellationToken cancellationToken);
  }

• Replace direct instantiation of NpgsqlConnection with a factory pattern to improve testability and reduce coupling:

  public class ConnectionFactory : IConnectionFactory {
      public DbConnection CreateConnection(string connectionString) {
          return new NpgsqlConnection(connectionString);
      }
  }

📚 Educational Notes:

• Dependency inversion is crucial in maintaining a clean architecture, where high-level modules should not depend on low-level modules, but both should depend on abstractions. This promotes a more maintainable and flexible codebase, especially important in systems like geospatial servers where underlying technologies may need to be swapped based on performance and scalability requirements.
• Asynchronous programming is vital in I/O-bound operations common in web servers to prevent blocking threads on the thread pool, which can lead to scalability issues under high load. This is especially critical in geospatial data handling which can be computationally and I/O intensive.

Overall Assessment: NEEDS_ATTENTION

CRITICAL: The PR is linked to a GitHub issue with clear acceptance criteria, and the changes address those criteria. However, the dependency inversion violation is a critical architectural concern that needs resolution before merging.

---

Automated architectural analysis powered by OpenAI GPT-4
This review focuses on architectural patterns and design decisions
Human review still recommended for complex changes