GeoViable System Architecture and Data Flow

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/danizd/geoviable/llms.txt

Use this file to discover all available pages before exploring further.

​

High-Level Architecture

Internet → Cloudflare (DNS + proxy) → Oracle Cloud VM :443
  → Nginx (SSL termination + reverse proxy)
    → /api/*  → geoviable-api:8000   (FastAPI + WeasyPrint + cron)
    → /*      → React static files   (/usr/share/nginx/html)

FastAPI ↔ geoviable-db:5432 (PostgreSQL 15 + PostGIS 3.4)
Cron Job → update_layers.py → monthly automated layer refresh

​

Docker Containers

​

Docker network

networks:
  geoviable-net:
    driver: bridge

​

Persistent volumes

​

Full Analysis Flow

1. User draws or uploads a polygon in the React + Leaflet interface. GeoJSON files and Shapefiles are parsed entirely client-side — no file is sent to the server at this stage.
2. Frontend validates the geometry: exactly 1 polygon, area < 100 km², vertex count < 10,000. Invalid geometries are rejected before any network request is made.
3. POST /api/v1/analyze — the frontend sends the validated polygon as a GeoJSON Feature in EPSG:4326 (WGS84 longitude/latitude).
4. FastAPI reprojects to EPSG:25830 using PostGIS ST_Transform. All stored environmental data is in ETRS89 / UTM zone 30N (EPSG:25830), so reprojection must happen before any spatial comparison.
5. PostGIS runs ST_Intersects + ST_Area against all seven environmental layers simultaneously. For each layer that intersects, the query also computes the intersection geometry, the area of that intersection in m², and the percentage of the parcel covered.
6. Results returned as JSON — the API response includes a per-layer breakdown of intersecting features, areas, and overlap percentages. The frontend overlays these geometries on the map using coloured polygons.
7. User clicks “Generate report” — the frontend calls POST /api/v1/report/generate, sending the same GeoJSON polygon plus the project name and metadata.
8. Backend generates the PDF:
   • Re-runs the spatial analysis (for data consistency and PDF autonomy).
   • Generates a static basemap image using contextily (tile download), matplotlib (rendering), and geopandas (vector overlay).
   • Renders the full report HTML from a Jinja2 template, embedding the basemap, all layer results, the risk score, and project metadata.
   • Converts the HTML to PDF using WeasyPrint.
9. PDF returned as application/pdf — the browser triggers an automatic file download.

​

PostGIS Query Pattern

-- Example: cross-reference with the Red Natura 2000 layer
SELECT
    rn.nombre,
    rn.tipo,                              -- 'ZEPA' or 'LIC/ZEC'
    rn.codigo,
    ST_Area(ST_Intersection(rn.geom, ST_Transform(ST_SetSRID(ST_GeomFromGeoJSON(:user_geojson), 4326), 25830))) AS area_interseccion_m2,
    ST_Area(ST_Transform(ST_SetSRID(ST_GeomFromGeoJSON(:user_geojson), 4326), 25830)) AS area_parcela_m2,
    ROUND(
        100.0 * ST_Area(ST_Intersection(rn.geom, ST_Transform(ST_SetSRID(ST_GeomFromGeoJSON(:user_geojson), 4326), 25830)))
        / ST_Area(ST_Transform(ST_SetSRID(ST_GeomFromGeoJSON(:user_geojson), 4326), 25830)),
        2
    ) AS porcentaje_solape
FROM red_natura_2000 rn
WHERE ST_Intersects(
    rn.geom,
    ST_Transform(ST_SetSRID(ST_GeomFromGeoJSON(:user_geojson), 4326), 25830)
);

• ST_GeomFromGeoJSON — parses the raw GeoJSON string into a PostGIS geometry.
• ST_SetSRID(..., 4326) — tags the geometry with its source CRS (WGS84).
• ST_Transform(..., 25830) — reprojects to ETRS89 / UTM zone 30N for metric area calculations.
• ST_Intersects — boolean spatial predicate; leverages the GIST index for performance.
• ST_Intersection — computes the actual overlapping geometry for area measurement.
• ST_Area — returns the area in square metres (since CRS is metric).

​

Coordinate Reference Systems

​

Monthly Automated Data Update

1. Download the Shapefile/ZIP from the official MITECO or CNIG source URL.
2. Decompress and read with GeoPandas.
3. Reproject to EPSG:25830 if the source CRS differs.
4. Filter records to the Galicia bounding box.
5. TRUNCATE + INSERT inside a single SQL transaction — if anything fails, ROLLBACK preserves the previous data intact.
6. Run VACUUM ANALYZE on the updated table.
7. Record the result (success or failure, timestamp, row count) in the layer_update_log table.

# Pseudocode for the transactional update strategy
with db.begin():
    db.execute(f"TRUNCATE TABLE {table_name}")
    gdf.to_postgis(table_name, db, if_exists="append", index=False)
# ROLLBACK happens automatically if any exception is raised

docker compose exec geoviable-api python -m scripts.update_layers

​

Dual-Endpoint Design

• POST /api/v1/analyze — runs the spatial analysis and returns JSON for map overlay. Used for interactive preview.
• POST /api/v1/report/generate — runs the full analysis again internally, generates the static map, and returns a PDF binary. The re-execution guarantees that the PDF is always self-consistent and does not depend on a prior /analyze call.

​

Where to go next