Wasstraat Archeologische Data

Een open-source platform dat archeologische gegevens verzamelt, verwerkt en toegankelijk maakt — van ruwe data naar gestructureerd inzicht.

Over het project

De Wasstraat functioneert als een digitale wasstraat voor archeologische data. Verspreide bronbestanden — Access-databases, Excel-sheets, foto's, rapporten en GIS-bestanden — worden geautomatiseerd ingelezen, opgeschoond, gekoppeld en gestructureerd opgeslagen.

Ontwikkeld voor de gemeente Delft, waar meer dan 1.000 opgravingen met tienduizenden foto's, vondstlijsten en rapporten (bijna 1 Terabyte aan data) zijn gedigitaliseerd.

Documentatie

Zie de volledige documentatie voor het uitgeklapte procesmodel en gedetailleerde uitleg per stap.

Architectuur

Het platform bestaat uit twee hoofdapplicaties die als Docker-containers draaien:

Applicatie	Doel	Poort
Airflow (airflow_app/)	Data verwerken (ETL-pipeline)	:8080
Flask App (app/)	Data inzichtelijk maken (web-interface)	:5051

Daarnaast draaien de volgende ondersteunende services:

Service	Rol	Poort
PostgreSQL	Definitieve relationele opslag	:5432
MongoDB	Ruwe opslag en staging	:27017
Elasticsearch	Fulltext-zoekindex	:9200
Redis	Caching	:6379
Apache	Statische bestanden (foto's)	:5052
Jupyter	Data-analyse notebooks	:8888

Verwerken van archeologische data

Het verwerken van alle archeologische data is uitgewerkt in procesmodellen in Apache Airflow. Het hoofdproces kent de volgende stappen:

1. Drop All Databases — Schoon alle data zodat gestart kan worden met verse databases.
2. Extract — Lees alle data uit externe bronnen in, as-is zonder transformatie. Voor Archeologie Delft zijn dat ongeveer 1.000 databases, ~100.000 foto's en enkele duizenden rapporten — in totaal bijna 1 TB aan data.
3. Transform1 Harmonize — Harmoniseer de veldnamen van alle ingelezen data over alle bronnen heen.
4. Transform2 Enhance Attributes — Maak de inhoud van alle velden consistent. Datumformaten, codes, projectnummers en metadata worden genormaliseerd.
5. Transform3 Set Keys — Genereer unieke sleutels en verwijzende sleutels voor alle entiteiten.
6. Transform4 Move and Merge — Voeg dubbele entiteiten samen met behoud van polymorfisme. Artefacten en Bestanden kunnen zo verschillende soorten hebben met eigen attributen.
7. Transform5 Set References — Ken integer-sleutels toe voor gebruik in de relationele database.
8. Load to Database & Index — Kopieer data naar PostgreSQL en bouw de Elasticsearch-zoekindex op.

Ondersteunde data

Categorie	Entiteiten
Basisgegevens	Project, Vindplaats, Vondst, Put, Vlak, Spoor, Vulling, Artefact, Monster, Bestand
Depotgegevens	Stelling, Standplaats, Plaatsing, Doos
Bestanden	Foto's, Tekeningen, Rapporten — elk met automatische metadata-extractie
Artefacten	Aardewerk, Glas, Metaal, Hout, Steen, Leer, Dierlijk Bot, Menselijk Bot, Kleipijp, Bouwaardewerk, Munt, Schelp, Textiel
Standaarden	ABR, GGM, CIDOC CRM, DANS e-Depot, Archis

Elke artefactcategorie kent eigen specifieke velden:

Snel starten

Vereisten

• Docker en Docker Compose
• GNU Make (standaard aanwezig op macOS en Linux)
• Minimaal 8 GB RAM beschikbaar voor Docker

Installatie

# Clone de repository
git clone https://github.com/brienen/wasstraat_archeologische_data.git
cd wasstraat_archeologische_data

# Start de wasstraat
# (config/*.env bestanden worden automatisch gegenereerd met unieke wachtwoorden)
make app

Tip: Bij de eerste start genereert init-config.sh automatisch alle config/*.env bestanden met unieke wachtwoorden. Om handmatig opnieuw te genereren: ./init-config.sh --force

Typ make help voor een overzicht van alle beschikbare commando's.

Omgevingen starten

make dev          # Ontwikkelomgeving (met hot-reload volumes)
make app          # Lokale modus (alle services)
make acc          # Acceptatieomgeving
make prod         # Productie (gepubliceerde images)
make stop         # Stop alle containers
make start        # Herstart gestopte containers
make logs         # Toon live logs
make ps           # Toon status van alle services

Eerste data verwerken

De repo bevat synthetische voorbeelddata in data/synthetic/data/ — twee fictieve opgravingsprojecten (SY001 en SY002) waarmee je de volledige pipeline kunt testen zonder eigen brondata. Dit is het startpunt om het platform te leren kennen.

Eigen data gebruiken? Organiseer je bronbestanden in data/<omgeving>/data/ conform deze structuur:

Directory	Inhoud	Formaat
projecten/	Per opgraving een subdirectory met projectdatabase + foto's	.mdb / .accdb
projectenlijst/	Projectoverzicht (tabel OPGRAVINGEN: code, locatie, jaar)	.mdb
magazijnlijst/	Depotadministratie (tabel magazijnlijst: stellingen, dozen)	.mdb
fotolijst/	Fotocatalogus (tabel Fotos: koppeling foto ↔ vondst)	.mdb
monsterdatabase/	Grondmonsters met botanische/zoölogische determinaties	.mdb
referentietabellen/	ABR-thesaurus (abr_versie_*.xlsx)	.xlsx

De Wasstraat doorzoekt elke directory recursief op .mdb/.accdb bestanden. In projecten/ bepaalt de directorynaam de projectcode. Zie data/synthetic/data/ als werkend voorbeeld en de documentatie voor details.

1. Open Airflow UI op http://localhost:8080
2. Start de DAG Extract_Transform_Load_Full_Cycle
3. Bekijk het resultaat in de Flask App op http://localhost:5051

Backup en restore

make backup                              # Backup PostgreSQL + MongoDB
make restore TS=2024-03-15_14-30-00      # Restore vanuit timestamp
make export                              # Exporteer alle tabellen als CSV

Testen

make install          # Eenmalig: maakt .venv aan met test-dependencies
make test             # Draai unit tests
make integration      # Integratietests met synthetische data
make integration-delft # Integratietests met Delftse data (indien aanwezig)
make test-all         # Unit + integratietests

Projectstructuur

wasstraat_archeologische_data/
├── airflow_app/          # Airflow ETL-applicatie
│   ├── dags/             # DAG-definities en transformatielogica
│   └── scripts/          # Shell-scripts voor data-import
├── app/                  # Flask web-applicatie
│   └── app/              # Models, views, API, templates
├── shared/               # Gedeelde modules (config, database, constanten)
├── config/               # Environment-bestanden (.env)
├── services/             # Dockerfiles per service
├── data/                 # Input- en outputdata
│   ├── input/basefiles/  # Bronbestanden (eigen data, niet in repo)
│   └── synthetic/        # Synthetische voorbeelddata (in repo)
├── tests/                # Unit- en integratietests
├── notebooks/            # Jupyter notebooks voor analyse
├── docs/                 # MkDocs documentatie
├── image/                # Afbeeldingen voor README
├── Makefile              # Alle commando's (make help)
├── docker-compose.yml    # Basis service-definities
├── docker-compose.test.yml     # Lichtgewicht test-databases
├── docker-compose.develop.yml  # Development overrides
├── docker-compose.acc.yml      # Acceptatie overrides
└── docker-compose.prod.yml     # Productie overrides

Documentatie

De volledige technische documentatie is beschikbaar als MkDocs-site:

make docs       # Start MkDocs dev-server op localhost:8000
make docs-build # Bouw statische site

De documentatie bevat:

• Projectoverzicht — Inleiding, probleemstelling en doelstellingen
• Aan de slag — Stap-voor-stap handleiding voor eerste gebruik
• Architectuur — Systeemarchitectuur, dataflow, componentenmodel, gegevensmodel en stack
• Componenten — Extractie, SingleStore, Transformatie, Crossviews, Validatie, Configuratie, Zoeken
• Deployment — Omgevingen, Airflow vs. App, proefdata inlezen
• Testen — Unit tests, integratietests en testinfrastructuur
• Diagrammen — draw.io architectuurdiagrammen

Technische stack

Categorie	Technologieën
Orchestratie	Apache Airflow 2.3.3
Backend	Python, Flask, Flask-AppBuilder
Databases	MongoDB 4.2, PostgreSQL, Elasticsearch 8.6
Caching	Redis
Infrastructuur	Docker Compose
Analyse	Jupyter Lab, Pandas, GeoPandas
Data-import	mdbtools, Pillow, pdf2image

Bijdragen

Bijdragen zijn welkom! Het project is open-source onder de EUPL-licentie.

1. Fork de repository
2. Maak een feature-branch (git checkout -b feature/mijn-verbetering)
3. Commit je wijzigingen (git commit -m 'Voeg verbetering toe')
4. Push naar de branch (git push origin feature/mijn-verbetering)
5. Open een Pull Request

Bij vragen of suggesties, open een issue.

Licentie

Dit project is uitgegeven onder de EUPL-1.2 licentie.

Contact

Ontwikkeld door E-Space (Arjen Brienen) in opdracht van de gemeente Delft. Het project wordt uitgebreid tot een generiek systeem voor andere Nederlandse gemeenten via Stichting Reuvens.