Web Interface Documentation

PyArchInit-Mini provides a modern web interface built with Flask, offering a responsive, user-friendly experience for managing archaeological data through any web browser.

Quick Start

Starting the Web Server

To start the web interface:

pyarchinit-mini-web

* Running on http://localhost:5001
* Debug mode: on

Access the interface at: http://localhost:5001

First Login

  1. Navigate to http://localhost:5001

  2. You’ll be redirected to the login page

  3. Default credentials:

    • Username: admin

    • Password: admin

  4. Important: Change the default password immediately

Interface Overview

Dashboard

The main dashboard provides:

  1. Overview Statistics

    • Total sites count

    • Total stratigraphic units

    • Total inventory items

    • Active users online

  2. Recent Activity

    • Latest sites added

    • Recent US entries

    • New inventory items

    • User activity feed

  3. Quick Actions

    • Create new site

    • Add stratigraphic unit

    • Register inventory item

    • Generate reports

Sites Management

Listing Sites

The sites list page (/sites) displays all archaeological sites in a responsive table/card view:

Features:

  • Pagination (20 items per page)

  • Search by name or location

  • Sort by any column

  • Quick actions (view, edit, delete)

  • Mobile-optimized card view

Table Columns:

  • ID

  • Site Name

  • Location (Nation)

  • Region

  • Comune

  • Province

  • Definition

  • Actions

Creating a Site

Click “New Site” to open the site creation form:

Required Fields:

  • Site name (unique)

Optional Fields:

  • Location/Nation

  • Region

  • Comune (municipality)

  • Province

  • Definition (Italian)

  • Definition (English)

Form Features:

  • Real-time validation

  • Auto-save draft

  • Multi-language support

  • Help tooltips

Editing Sites

Click the edit button to modify site information:

  1. Form pre-populated with current data

  2. Change tracking (shows modified fields)

  3. Validation before save

  4. Confirmation for critical changes

Site Details

The site detail page shows:

  • Complete site information

  • Related stratigraphic units count

  • Inventory items count

  • Quick links to related data

  • Export options

Stratigraphic Units (US) Management

US List Page

Access via /us or sidebar:

Features:

  • Filter by site

  • Filter by area

  • Search in descriptions

  • Advanced filters (period, type)

  • Bulk operations

US Form (49 Fields)

The US form is organized into 6 tabs:

1. Dati Generali (General Data)

  • Sito* (Site - required)

  • Area

  • US* (Unit number - required)

  • Definizione stratigrafica

  • Definizione interpretativa

  • Anno di scavo

2. Dati Stratigrafici (Stratigraphic Data)

  • Periodo iniziale

  • Fase iniziale

  • Periodo finale

  • Fase finale

  • Attività

  • Unità tipo (US, USM, USD, USV, VSF)

3. Caratteristiche (Characteristics)

  • Formazione

  • Colore

  • Consistenza

  • Modo di formazione

  • Inclusi

  • Componenti organici

  • Componenti inorganici

4. Rapporti Stratigrafici (Relationships)

  • Si lega a

  • Uguale a

  • Copre

  • Coperto da

  • Riempie

  • Riempito da

  • Taglia

  • Tagliato da

  • Si appoggia a

  • Gli si appoggia

5. Documentazione (Documentation)

  • Documentazione (text)

  • Osservazioni

  • Interpretazione

  • Elementi datanti

  • Campioni

  • Piante

  • Sezione/Prospetto

  • Foto

6. Misurazioni (Measurements)

  • Lunghezza max

  • Altezza max

  • Profondità max

  • Volume

  • Superficie

Form Behavior

  • Tab validation (red indicator if errors)

  • Auto-save to localStorage

  • Relationship validation

  • ICCD thesaurus integration

  • Real-time collaboration updates

Inventory Management

Inventory List

The inventory page (/inventario) provides:

  • Advanced filtering options

  • Image thumbnails

  • Conservation state indicators

  • Export selected items

  • Print labels

Inventory Form (37 Fields)

Organized in 8 tabs:

1. Dati Principali

    1. Inventario* (required)

  • Tipo reperto

  • Classe materiale

  • Definizione

  • Stato conservazione

2. Dati di Scavo

  • Sito

  • Area

  • US

  • Quadrato

  • Ambiente

3. Misurazioni

  • Lunghezza

  • Larghezza

  • Altezza

  • Diametro

  • Peso

  • EVE (Estimated Vessel Equivalent)

4. Tecnologia

  • Tipo oggetto

  • Funzione

  • Descrizione

  • Corpo ceramico

  • Rivestimento

  • Decorazione

5. Elementi di Datazione

  • Datazione reperto

  • Criterio datazione

  • Bibliografia

6. Quantificazione

  • Frammenti

  • Totale frammenti

  • Tipo quantità

7. Morfologia

  • Forma

  • Tipologia

  • Confronti

8. Conservazione

  • Luogo conservazione

  • Lavato

  • Restaurato

  • Catalogato

Harris Matrix Visualization

Interactive Features

Access via Tools → Harris Matrix:

  1. Site Selection

    • Dropdown of available sites

    • Unit count preview

  2. Visualization Options

    • Grouping: period+area, period, area, none

    • Export format: PNG, PDF, SVG

    • Resolution settings

  3. Interactive Graph

    • Pan and zoom

    • Node clicking for details

    • Relationship highlighting

    • Period color coding

GraphML Export

Export to yEd format:

  1. Select site

  2. Choose “Export GraphML (yEd)”

  3. Configure options:

    • Include descriptions

    • EM_palette styling

    • Custom metadata

  4. Download .graphml file

Analytics Dashboard

Real-time analytics with 8 chart types:

Overview Cards

  • Total sites

  • Total US count

  • Total finds

  • Geographic spread

Interactive Charts

  1. Sites by Region (Pie chart)

  2. Sites by Province (Bar chart)

  3. US by Period (Horizontal bar)

  4. US by Type (Doughnut chart)

  5. Finds by Type (Bar chart)

  6. Conservation State (Pie chart)

  7. US per Site (Top 10 bar)

  8. Finds per Site (Top 10 bar)

Chart Features:

  • Hover tooltips

  • Click to filter

  • Export as image

  • Print view

Export/Import Interface

Web-based import/export:

Export Options

  1. Select data type (Sites/US/Inventory)

  2. Choose format (Excel/CSV)

  3. Apply filters (optional)

  4. Click Export

  5. Download starts automatically

Import Process

  1. Select data type

  2. Upload CSV/Excel file

  3. Preview data mapping

  4. Configure options:

    • Skip duplicates

    • Update existing

    • Validation rules

  5. Review import summary

Real-time Collaboration

WebSocket Features

The web interface includes real-time updates:

Online Users Badge

  • Shows count of connected users

  • Updates automatically

  • Click to see user list

Live Notifications

Toast notifications for:

  • User connections/disconnections

  • Data creation

  • Data modifications

  • Data deletions

Activity Types:

  • “User X created site Y”

  • “User X modified US Z”

  • “User X deleted inventory item”

Notification Settings:

  • Position: top-right

  • Duration: 5 seconds

  • Sound: optional

  • Persistence: important alerts

Media Management

Upload Interface

Access via Tools → Upload Media:

  1. Drag & Drop Zone

    • Multiple file support

    • Progress indicators

    • Auto-thumbnail generation

  2. File Types

    • Images: JPG, PNG, GIF

    • Documents: PDF, DOC, DOCX

    • Videos: MP4, AVI, MOV

    • Max size: 100MB

  3. Metadata

    • Title

    • Description

    • Tags

    • Related entity (Site/US/Inventory)

Internationalization

Language Support

Full support for Italian and English:

Switching Languages:

  1. Click flag icon in navbar

  2. Select IT or EN

  3. Page reloads in selected language

  4. Preference saved in session

Translated Elements:

  • All interface text

  • Form labels and help

  • Error messages

  • Chart labels

  • Export headers

Administration

Database Management

Admin-only features:

Upload Database:

  1. Navigate to Database → Upload

  2. Select .db file

  3. Validation checks

  4. Replace or merge options

Connect PostgreSQL:

  1. Database → Connect

  2. Enter connection details

  3. Test connection

  4. Save configuration

Database Info:

  • Current connection

  • Table statistics

  • Health check

User Management

Manage users (admin only):

User List:

  • Username

  • Email

  • Role

  • Last login

  • Actions

Create User:

  1. Click “New User”

  2. Fill required fields:

    • Username

    • Email

    • Password

    • Role (Admin/Operator/Viewer)

Edit User:

  • Change role

  • Reset password

  • Enable/disable account

Responsive Design

Mobile Optimization

The interface adapts to different screen sizes:

Phone (< 768px):

  • Single column layout

  • Card view for lists

  • Bottom action buttons

  • Touch-optimized controls

  • Minimum 44px touch targets

Tablet (768-991px):

  • Two column layout

  • Collapsible sidebar

  • Optimized forms

  • Readable font sizes

Desktop (≥ 992px):

  • Full sidebar

  • Multi-column tables

  • Hover interactions

  • Keyboard shortcuts

Performance Features

Optimization Techniques

  1. Lazy Loading

    • Images load on scroll

    • Pagination for large datasets

    • Deferred JavaScript

  2. Caching

    • Static assets cached

    • API responses cached

    • LocalStorage for drafts

  3. Compression

    • Gzip enabled

    • Minified CSS/JS

    • Optimized images

Security Features

Built-in Security

  1. Authentication Required

    • All pages protected

    • Session timeout

    • Remember me option

  2. CSRF Protection

    • Tokens on all forms

    • Automatic validation

  3. Input Validation

    • Client-side validation

    • Server-side validation

    • SQL injection prevention

  4. File Upload Security

    • Type validation

    • Size limits

    • Virus scanning (optional)

Browser Support

Supported Browsers

  • Chrome 90+

  • Firefox 88+

  • Safari 14+

  • Edge 90+

  • Mobile Chrome/Safari

Not Supported:

  • Internet Explorer

  • Older browser versions

Keyboard Shortcuts

Available shortcuts:

  • Ctrl+N: New item (context-aware)

  • Ctrl+S: Save current form

  • Ctrl+F: Focus search

  • Ctrl+E: Export data

  • ESC: Close modals

  • ?: Show shortcuts help

Configuration

Web-specific settings in config.yaml:

web:
  host: "0.0.0.0"
  port: 5001
  debug: true
  secret_key: "change-this-in-production"
  session_lifetime: 1800  # 30 minutes
  max_upload_size: 104857600  # 100MB
  allowed_extensions: ["jpg", "png", "pdf", "doc"]
  enable_socketio: true
  cors_origins: ["http://localhost:3000"]