Web Interface Complete Tutorial

Added in version 1.7.13: Complete visual tutorial with 63 screenshots covering all Web GUI features

This tutorial provides a complete visual walkthrough of the PyArchInit-Mini Web interface, covering all features, forms, and functions with real screenshots.

Prerequisites

• PyArchInit-Mini v1.7.13+ installed (pip install pyarchinit-mini)

• Python 3.8 or higher

• Modern web browser (Chrome, Firefox, Safari, Edge)

• SQLite or PostgreSQL database

Starting the Web Server

Launch the web interface from command line:

# Start with default database
pyarchinit-mini-web

# Start with specific database
DATABASE_URL="sqlite:///data/pyarchinit_mini.db" python3 -m pyarchinit_mini.web_interface.app

# Start on custom port
PYARCHINIT_WEB_PORT=8080 pyarchinit-mini-web

The web interface will be available at: http://localhost:5001

Note

Port 5001 is used by default to avoid conflicts with AirPlay on macOS (which uses port 5000).

Getting Started

Authentication

Login Page - Entry point to PyArchInit-Mini Web GUI

The login page is the entry point to the system.

Default Credentials:

• Username: admin

• Password: admin

Warning

In production environments, always change the default credentials immediately after first login.

Login Process:

1. Enter Username

Username field highlighted

2. Enter Password

Password field highlighted

3. Click Login Button

Login button highlighted

Security Features

• Session-based authentication

• Role-based access control (Admin, Operator, Viewer)

• Secure password hashing with bcrypt

• Auto-logout on browser close

Dashboard

Main Dashboard - Overview of system statistics and quick navigation

After logging in, the dashboard provides:

Statistics Cards:

• Total Sites count

• Total Stratigraphic Units (US)

• Total Inventory Items

• Database information

• System version (v1.7.13)

Recent Activity:

• Latest created sites

• Recent stratigraphic units

• Recent inventory additions

Quick Navigation:

• Access all major modules from top navigation menu

• Responsive design adapts to screen size

• Real-time statistics updates

Site Management

Sites are the top-level organizational units representing archaeological sites or excavation areas.

Site List

Sites List - Paginated list of all archaeological sites

Features:

• Paginated list (20 sites per page)

• Search by site name

• Quick view of location (Nation, Region, Province, Municipality)

• Direct links to site details

• Create new site button

Site Detail View

Site Detail - Complete site information with related data

The site detail page shows:

• Complete site information

• Associated stratigraphic units

• Related inventory items

• Geographic location details

• Edit and delete options

Creating a New Site

Site Form - Create or edit site information

Required Fields:

• Site Name (Nome Sito)

Optional Fields:

• Nation (Nazione)

• Region (Regione)

• Province (Provincia)

• Municipality (Comune)

• Site Definition (Definizione Sito)

• Description (Descrizione)

• English translations for definition and description

Form Features:

• Client-side validation

• i18n support (Italian/English)

• Auto-save draft functionality

• Cancel to return to list

Stratigraphic Units (US)

The US (Unità Stratigrafiche) module manages stratigraphic units with comprehensive archaeological data organized across 6 tabs.

US List

US List - Stratigraphic units with advanced filtering

Features:

• Paginated list with advanced filtering

• Filter by site, area, unit type, year

• Quick view of US number, site, and area

• Color-coded by unit type

• Bulk operations support

Creating a New US

The US form is organized into 6 comprehensive tabs for better data organization.

Tab 1: Basic Information

Tab 1: Basic Information - Site selection and primary identification fields

Required Fields:

• Site (Sito) - Select from dropdown

• US Number (Numero US) - Unique stratigraphic unit identifier within the site

Optional Fields:

• Area (Area) - Excavation area or sector

• Year (Anno) - Excavation year

• Archaeologist (Archeologo) - Person responsible for excavation

Tip

The combination of Site + US Number must be unique in the system.

Tab 2: Descriptions

Tab 2: Descriptions - Stratigraphic and interpretative descriptions

Fields:

• Stratigraphic Description (Descrizione Stratigrafica) - Objective physical description

• Interpretative Description (Descrizione Interpretativa) - Archaeological interpretation

• Detailed Description (Descrizione Estesa) - Extended description with additional details

• Interpretation (Interpretazione) - Functional/chronological interpretation

• Observations (Osservazioni) - Additional observations and notes

Tip

Tip: Specifying the initial and final period helps to chronologically contextualize the stratigraphic unit in the archaeological site.

Tab 3: Physical Characteristics

Tab 3: Physical Characteristics - Material properties and composition

Fields:

• Unit Type (Tipo US) - e.g., Layer (Strato), Cut (Taglio), Fill (Riempimento)

• Formation Type (Tipo Formazione) - Natural (Naturale) / Artificial (Artificiale)

• Color (Colore) - Munsell or descriptive color

• Consistency (Consistenza) - Soil consistency description

• Texture (Tessitura) - Grain size and texture

• Compaction (Compattezza) - Degree of compaction

• Inclusions (Inclusioni) - Materials present in the matrix

• Soil composition details

Tab 4: Chronology

Tab 4: Chronology - Dating and periodization

Periodization Section:

• Initial Period (Periodo Iniziale) - Starting chronological period (select from dating periods table)

• Final Period (Periodo Finale) - Ending chronological period

• Dating (Datazione) - Dating method and results dropdown

• Reliability (Affidabilità) - Dating reliability assessment

Tip

Use the standardized dating periods from the Datazione table for consistency across the project.

Tab 5: Stratigraphic Relationships

Tab 5: Stratigraphic Relationships - Define stratigraphic connections for Harris Matrix

Relationship Types:

• Covers (Copre) - This US covers/overlies another US

• Covered by (Coperto da) - This US is covered by another US

• Cuts (Taglia) - This US cuts through another US

• Cut by (Tagliato da) - This US is cut by another US

• Fills (Riempie) - This US fills a cut

• Filled by (Riempito da) - This US (a cut) is filled by another US

• Equals (Uguale a) - This US is the same as another US

• Adjacent to (Si appoggia a) - This US is adjacent to another US

Text Format Example:

copre 1002, 1003
taglia 1005
si appoggia a 1010, 1011

These relationships are automatically used to generate the Harris Matrix.

Tip

Use consistent relationship definitions to ensure accurate Harris Matrix generation. Each relationship should be reciprocal (if US 1001 covers 1002, then 1002 is covered by 1001).

Tab 6: Documentation

Tab 6: Documentation - Media attachments and references

Features:

• Photo uploads and gallery

• Drawing attachments

• 3D model links

• Document references

• Bibliography

• Media metadata management

Note

Media files are stored in the uploads directory and linked to the US record. Supported formats: JPG, PNG, PDF, DXF, OBJ.

Advanced US Features

Navigation:

• Previous/Next buttons to navigate between records

• Position counter (e.g., “Record 5 of 20”)

• Respects active filters

Data Validation:

• Required field checking

• US number uniqueness validation

• Relationship syntax validation

• Date format validation

Material Inventory

The Inventario module manages archaeological finds and materials with 8 specialized tabs following ICCD (Istituto Centrale per il Catalogo e la Documentazione) standards.

Inventory List

Inventory List - Material finds with filtering

Features:

• Paginated list with filters

• Filter by site, area, US, artifact type

• Material type icons

• Conservation state indicators

• Quick search by inventory number

• Direct links to artifact details

Creating a New Inventory Item

The inventory form spans 8 comprehensive tabs organized to capture complete artifact documentation.

Tab 1: Identification

Tab 1: Identification - Basic artifact identification and recording information

Required Fields:

• Site (Sito) - Select from dropdown

• Inventory Number (Numero Inventario) - Unique identifier

Optional Fields:

• Artifact Number (N. Reperto)

• Recorder (Schedatore) - Person who catalogued the artifact

• Record Date (Date Scheda) - Date of cataloging (Format: YYYY-MM-DD)

• Year (Years) - Excavation or discovery year

Tip

The combination of Site + Inventory Number must be unique in the system.

Tab 2: Classification

Tab 2: Classification - Typological classification and description

Fields:

• Artifact Type (Tipo Reperto) - Controlled vocabulary from thesaurus (e.g., Ceramic, Metal, Stone, Bone, Glass)

• Recording Criteria (Criterio Schedatura) - Documentation method used

• Definition (Definizione) - Specific object definition

• Type (Tipo) - Typological classification

• Container Type (Tipo Contenitore) - For vessel artifacts

• Structure (Struttura) - Structural characteristics

• Description (Descrizione) - Detailed artifact description (long text field)

Note

Artifact Type uses controlled vocabulary from the ICCD Thesaurus for consistency.

Tab 3: Context

Tab 3: Context - Archaeological context and stratigraphic provenance

Fields:

• Area (Area) - Excavation area where artifact was found

• SU (US) - Associated Stratigraphic Unit number

• Find Spot (Punto Rinv) - Precise location within the SU

• Artifact Elements (Elementi Reperto) - Description of constituent elements

Tip

Archaeological Context Information: This tab links the artifact to its stratigraphic origin, essential for understanding depositional context and dating.

Tab 4: Physical Characteristics

Tab 4: Physical Characteristics - Material properties and storage

Fields:

• Conservation State (Stato Conservazione) - Controlled vocabulary from thesaurus

• Washed (Lavato) - Yes/No dropdown

• Box Number (Nr. Cassa) - Storage box identifier

• Storage Location (Luogo Conservazione) - Current storage facility/room

Note

Conservation State uses standardized terms from the ICCD Thesaurus.

Tab 5: Conservation & Management

Tab 5: Conservation - Cataloging status and diagnostic significance

Fields:

• Catalogued (Repertato) - Yes/No - Has the artifact been photographically documented?

• Diagnostic (Diagnostico) - Yes/No - Is the artifact significant for dating the layer?

Tips Box:

• Catalogued: Indicates if the artifact has been photographically documented

• Diagnostic: Indicates if the artifact is significant for dating the layer

Important

Diagnostic artifacts are particularly important for chronological interpretation of the stratigraphic sequence.

Tab 6: Ceramic Characteristics

Tab 6: Ceramic - Specialized fields for ceramic artifacts

Fields:

• Ceramic Body (Corpo Ceramico) - Controlled vocabulary from thesaurus (fabric type)

• Coating (Rivestimento) - Controlled vocabulary from thesaurus (surface treatment)

• Rim Diameter (Diametro Orlo) - In centimeters (e.g., 12.5)

• Rim EVE (Eve Orlo) - Estimated Vessel Equivalent (preserved fraction 0-1, e.g., 0.25)

Note

This tab is specific for ceramic artifacts. EVE (Estimated Vessel Equivalent) indicates the preserved fraction of the rim circumference.

Tab 7: Measurements

Tab 7: Measurements - Weight and quantitative data

Weight and Quantitative Measurements (Card Section):

• Weight (Peso) - In grams (e.g., 125.5)

• Total Fragments (Totale Frammenti) - Number of fragments (e.g., 5)

• Minimum Forms (Forme Minime) - Minimum number of individuals (e.g., 1)

• Maximum Forms (Forme Massime) - Maximum number of individuals (e.g., 3)

Additional Field:

• Detailed Measurements (Misurazioni) - Free text for other measurements: length, width, height, thickness, etc.

Tip

Minimum and Maximum Forms help estimate the number of individual vessels represented by the fragments.

Tab 8: Documentation

Tab 8: Documentation - Dating, technology, and bibliographic references

Fields:

• Artifact Dating (Datazione Reperto) - Proposed chronological attribution

• Technologies (Tecnologie) - Production and processing techniques (long text)

• Bibliographic References (Rif. Biblio) - Citations related to the artifact (long text)

• Photo Negative (Negativo Photo) - Negative reference number

• Slide (Diapositiva) - Slide reference number

Note

Use this tab to document technical analysis, parallels, and scholarly references that support artifact interpretation.

Upload Media

The Media Upload tool allows you to attach photos, drawings, and documents to archaeological records.

Upload Media - File upload for Sites, US, and Inventory items

Upload Interface:

• Entity Type selection (Site, US, Inventory)

• Entity ID association

• File upload with drag-and-drop support

• Description and metadata fields

• Author/Photographer attribution

Supported File Types:

• Images: JPG, PNG, TIFF, RAW

• Documents: PDF, DOC, DOCX

• Drawings: DWG, DXF, SVG

• 3D Models: OBJ, PLY, STL

Features:

• Multiple file upload

• Automatic thumbnail generation

• Image EXIF data extraction

• File size validation

• Organized by entity and type

Tip

Photos and drawings can be linked to specific stratigraphic units or inventory items for complete documentation.

Harris Matrix Creator

Interactive visual editor for creating and editing Harris Matrix diagrams.

Harris Matrix Creator - Interactive graphical editor with Extended Matrix support

Visual Editor Features:

• Drag-and-drop node creation

• Interactive relationship connections

• Real-time visual preview

• Zoom and pan navigation

• Auto-layout algorithms

Extended Matrix Support:

• 14 different node types (US, USM, USVA, DOC, Extractor, etc.)

• 14 relationship types (Covers, Cuts, Continuity, etc.)

• Period and area grouping

• Custom node descriptions

• Color-coded node types

Database Integration:

• Save directly to database

• Edit existing matrices

• Automatic validation

• Relationship consistency checks

Export Options:

• Export to GraphML (yEd compatible)

• Export to DOT (Graphviz)

• High-resolution PDF rendering

• Share with colleagues

Alternative: CSV/Excel Import:

For users who prefer working with spreadsheets, Harris Matrices can also be created by importing CSV or Excel files using the command-line tool.

Harris Matrix Visualization

View and analyze the generated Harris Matrix diagrams with interactive tools.

Harris Matrix View - Interactive stratigraphic diagram with depth levels

Visualization Features:

• Hierarchical stratigraphic sequence display

• Maximum depth level calculation

• Node relationships visualization

• Graphviz rendering engine

• Zoom and navigation controls

Matrix Information:

• Total stratigraphic units count

• Relationship connections display

• Stratigraphic sequence by levels

• Period and area grouping

GraphML Export

Export Harris Matrix diagrams in GraphML format for advanced editing with yEd Graph Editor.

GraphML Export - Advanced export options with Extended Matrix support

Export Parameters:

• Archaeological Site selection

• Diagram title customization

• Grouping options (Period + Area)

• Period order (Normal/Reverse)

Export Formats:

• GraphML: yEd Graph Editor compatible format with complete metadata

• s3Dgraphy (Extended Matrix): Export in Heriverse/ATON format with 3D model support

• Interactive Viewer: Web-based interactive stratigraphic viewer

s3Dgraphy Features:

• Complete metadata for each SU

• 3D model support (GLB/GLTF)

• Extended Matrix Framework compliant

• Heriverse/ATON wrapper with CocoDrill semantic shapes

• Interactive 3D stratigraphy viewer

Tip

Download yEd Graph Editor from https://www.yworks.com/products/yed for advanced diagram editing and automatic layout algorithms.

Excel/CSV Import

Import stratigraphic data from Excel files and generate Extended Matrix.

Excel Import - Bulk import from Excel files with Harris Matrix generation

Excel Format Options:

• Harris Matrix Template: Sheet-based format with separate NODES and RELATIONSHIPS sheets

• Extended Matrix Parser: Inline format with relationships in columns

Import Process:

1. Select Excel format type

2. Upload Excel file (.xlsx, .xls, .csv)

3. Enter archaeological site name

4. Optionally generate GraphML for visualization

5. Click Import Excel

Generated Output:

• US records in database

• Stratigraphic relationships

• Periodization data

• GraphML file for visualization (optional)

Note

Example Excel files are provided for testing both Harris Template and Extended Matrix formats.

Data Import/Export

PyArchInit-compatible import and export for data migration and backup.

PyArchInit Import/Export - Data migration between PyArchInit databases

Import from PyArchInit Database

Import Interface - Migrate data from PyArchInit full version

Import Options:

• Source database type: SQLite or PostgreSQL

• Database file path selection

• Test connection before import

• Select which tables to import:

  • Siti (Sites)

  • US - Stratigraphic Units

  • US Relationships (from rapporti field)

  • Inventario Materiali (Material Inventory)

  • Periodizzazione (Periodization)

  • Thesaurus

• Optional site filtering

Datazione Sync:

After import, use the “Sync Datazioni from Periodizzazione” button to synchronize dating period data with US datazione fields.

Export to PyArchInit Format

Export Interface - Export data to PyArchInit-compatible database

Export Features:

• Create new SQLite database compatible with PyArchInit

• Export selected tables

• Maintain data integrity and relationships

• Backup current project data

Create New Database

Create Database - Initialize new empty PyArchInit-Mini database

Database Creation:

• Create new SQLite database file

• Initialize complete schema

• Set up all tables and relationships

• Ready for immediate use

Extended Matrix Node Configuration

Configure node types for Extended Matrix Framework diagrams.

EM Node Configuration - Manage 10 standard stratigraphic and 4 non-stratigraphic node types

Built-in Node Types:

Stratigraphic Units (10 types):

• US: Standard stratigraphic unit (rectangle, white/brown)

• USM: Masonry stratigraphic unit (rectangle, white/brown)

• VSF: Virtual stratigraphic face (roundrectangle, white/yellow)

• SF: Stratigraphic face (octagon, white/yellow)

• USD: Destructive stratigraphic unit (roundrectangle, white/brown)

• USVA: Virtual stratigraphic unit A (parallelogram, black/blue)

• USVB: Virtual stratigraphic unit B (hexagon, black/green)

• USVC: Virtual stratigraphic unit C (hexagon, black/green)

• TU: Typological unit (rectangle, white/brown)

• CON: Connector/continuity node (svg, white/white)

Non-Stratigraphic Units (4 types):

• DOC: Documentation node

• Extractor: Data extractor node

• Combiner: Data combiner node

• Property: Property/attribute node

Node Configuration:

• Label format with placeholders (e.g., US{number})

• Symbol type for GraphML export

• Shape for visualization

• Colors (fill and border)

• Read-only for built-in types

• Custom types can be added/edited/deleted

Dating Periods Management

Manage standardized chronological periods for consistent dating across the project.

Dating Periods - Chronological period definitions

Create New Dating Period

Dating Period Form - Define chronological periods with date ranges

Period Fields:

• Period name (e.g., “Bronze Age”, “Roman Imperial”)

• Start date (numeric or BCE/CE)

• End date

• Description and notes

• Parent period (for hierarchical periodization)

• Geographic scope

Usage:

These standardized periods are used throughout the system for:

• US chronology tab

• Material inventory dating

• Site periodization

• Temporal analysis and queries

Periodization Records

Define and manage archaeological periodization schemes.

Periodization Records - Archaeological period definitions

Periodization Features:

• Multiple periodization schemes per site

• Hierarchical period structure

• Cultural period associations

• Chronological boundaries

• Period descriptions

ICCD Thesaurus

Manage controlled vocabulary from the Italian Central Institute for Cataloging and Documentation (ICCD).

ICCD Thesaurus - Controlled terminology management

Thesaurus Management

Thesaurus Management - Add and edit controlled terms

Vocabulary Categories:

• Object types (Tipo Oggetto)

• Materials (Materiali)

• Techniques (Tecniche)

• Conservation states (Stati di Conservazione)

• Functional categories (Categorie Funzionali)

Features:

• Hierarchical term structure

• Multilingual support

• Term relationships (broader/narrower)

• ICCD standard compliance

• Search and filtering

Analytics Dashboard

Statistical analysis and reporting tools for archaeological data.

Analytics - Data visualization and statistics

Analytics Features:

• Site statistics overview

• US distribution by type

• Material inventory summaries

• Chronological distribution charts

• Relationship network analysis

• Export reports to PDF/Excel

Stratigraphic Validation

Validate stratigraphic relationships and identify potential inconsistencies.

Validation Report - Stratigraphic consistency checks

Validation Checks:

• Relationship reciprocity (if A covers B, then B is covered by A)

• Circular relationship detection

• Orphaned units identification

• Missing critical relationships

• Chronological inconsistencies

Administration

System administration tools for database and user management.

Database Management

Database Administration - Database operations and maintenance

Upload Database

Upload Database - Import existing SQLite databases

Connect to Database

Database Connection - Configure database connection settings

User Management

User Management - Manage application users and permissions

User Administration:

• Create new users

• Edit user profiles

• Assign roles (Admin, Operator, Viewer)

• Enable/disable user accounts

• Password reset

• Activity monitoring

Access Levels:

• Admin: Full system access including administration

• Operator: Create and edit archaeological data

• Viewer: Read-only access to data

Next Steps

Congratulations! You have completed the PyArchInit-Mini web interface tutorial.

You now know how to:

• Log in to the web application

• Create and manage archaeological sites

• Document stratigraphic units with all their attributes

• Record material inventory finds with ICCD-compliant fields

• Upload and manage media files

• Create and visualize Harris Matrix diagrams

• Export diagrams to GraphML and Extended Matrix formats

• Import data from Excel/CSV files

• Manage PyArchInit database import/export

• Configure Extended Matrix node types

• Define dating periods and periodization schemes

• Manage ICCD thesaurus terms

• View analytics and validation reports

• Administer databases and users

For more advanced features and workflows, refer to the Python API Guide and the Command Line Tools.

Additional Resources

• Installation Guide

• Python API Reference

• Command Line Reference

• GitHub Repository

• Issue Tracker