Prepare project for archival

README.md

@@ -0,0 +1,48 @@
+# Perl-Dam
+
+**perl-dam** is a modular Perl library that simplifies the creation of interactive query forms and
+filtered data listings through a menu-based interface. It includes reusable components to define UI
+filters, manage user sessions, generate SQL queries, and control data access securely.
+
+# Features
+
+  - Build dynamic query forms with reusable filter controls
+  - Generate custom data listings from SQL queries
+  - Export results to CSV or generate printable PDF reports
+  - Fine-grained access control for users and groups
+  - Modular structure with customizable UI components and templates
+  - Session management and error handling tools included
+
+## Project Layout
+
+```
+perl-dam/
+├── Dam/                  # Core library
+│   ├── Application.pm    # High‑level application wrapper
+│   ├── DamLogic.pm       # Session handling, rendering, permissions
+│   ├── Database.pm       # Lightweight DBI wrapper + SQL helpers
+│   ├── Debug.pm          # Debugging and logging utilities
+│   ├── Util.pm           # Generic helper functions
+│   ├── Var.pm            # Global constants
+│   └── Components/       # Reusable UI pieces
+│       ├── Controls/     # Filter widgets (Date.pm, Option.pm, Upload.pm…)
+│       ├── Actions/      # Listing actions (Download.pm, Print.pm, Sort.pm)
+│       ├── Templates/    # Template Toolkit (.tt) snippets for each control
+│       └── Translations/ # Locale strings for UI texts
+└── www/                  # Sample web front‑end (static assets)
+    └── dam/
+        ├── css/          # Bootstrap + custom styles
+        ├── js/           # jQuery, validators, menus, charting
+        ├── fonts/        # Web‑fonts used by templates
+        └── img/          # Icons and generic imagery
+```
+
+## Key Modules
+
+| Module | Purpose |
+| ------ | ------- |
+| **Dam::DamLogic** | Central dispatcher; builds menus, enforces permissions, renders forms & listings. |
+| **Dam::Database** | Wraps DBI to assemble SQL from filter definitions and execute safely. |
+| **Dam::Components::Controls** | Individual widgets (DateRange, MultiCheck, Year…) used to build query forms. |
+| **Dam::Components::Actions** | Post‑listing operations: CSV export, PDF generation, sorting. |
+| **Dam::Application** | Thin application entry point—integrate it in CGI/FCGI/PSGI scripts. |