Code Structure and Modules

Warning

This page is under review and may contain incorrect information.

The Xolmis Desktop application is designed for clarity, maintainability, and extensibility. Built using Free Pascal and the Lazarus IDE, the codebase is modular by design, allowing researchers and developers to easily add features or fix bugs without breaking unrelated functionality.

Folder structure

Top-level Folder Structure

• bin: Dynamic link libraries (DLLs) used at runtime.
• components: Custom Lazarus components developed or adapted for Xolmis.
• docs: Source files for generating the user guide and manuals.
• languages: Internationalization files — translation resources for UI.
• reports: Report templates for exporting structured summaries or statistics.
• resources: Miscellaneous supporting files such as icons, sounds, and config snippets.
• source: Source files of Xolmis.
• source_docs: FPDoc-compatible documentation for internal units.

The MkDocs configuration file (mkdocs.yml) and the Inno Setup script (xolmis-setup.iss) are in the root directory.

Main Source Folder

All core logic and GUI functionality resides inside the /source folder, segmented into specific technical domains:

• data: Database schemas, SQL helpers, and persistent storage logic.
• data modules: All data module units.
• dialogs: Generic and custom dialog units for auxiliary tasks (e.g., confirmation, selection).
• edit_dialogs: Dialogs specifically designed for creating and editing records.
• io: Import and export libraries.
• models: ORM-style classes representing database entities and encapsulating business logic.
• screens: Main application forms — includes navigation, dashboard, and tabbed data views.
• utils: Shared libraries: converters, validators, enums, constants, and system tools.

The Lazarus .lpi and .lpr project files reside in the /source directory, referencing necessary units for compilation.

Core Concepts

The Xolmis codebase adheres to several important architectural ideas:

• Strong Typing with Custom Enums: Domain entities are mapped to TTableType enums for safe internal referencing.
• Object-Oriented Design: Each module encapsulates data handling, UI, and validation logic using class structures.
• Loose Coupling, High Cohesion: Modules interact via well-defined interfaces and event systems.

Key Modules Breakdown

Here’s a snapshot of several key domain modules and their structure:

Module Name	Purpose
Gazetteer	Manage toponyms data
Sampling plots	Manage sampling plots or net stations and permanent nets data
Institutions	Store institutions data
Researchers	Store people data
Projects	Manage projects data, goals, chronogram, budgets, and expenses
Permits	Store legal and institutional permit info
Taxa	Store the ornithological taxonomy (read only)
Botanical taxa	Manage the botanical taxonomy
Methods	Store sampling methods info
Expeditions	Store fieldwork expeditions info
Surveys	Manage surveys, mist nets, weather log, and vegetation data
Sightings	Manage bird sightings data
Specimens	Manage collected samples data
Bands	Manage the bird bands stock (CEMAVE/Brazil)
Individuals	Store individual birds' info
Captures	Store bird captures and measurements data
Feathers	Handle feather samples and traits
Nests	Track nesting data and related entries, including nest revisions and eggs
Media	Associate photos, sound, and documents

Each module includes:

• A data model class (T[Entity])
• A data controller class (T[Entity]Repository)
• A form/unit for user interface interaction (insert/edit routines)
• Validation routines and mapping helpers

Module models live in the /source/models directory:

• models_record_types.pp: Ancestor record classes
• models_bands.pp: Classes of bands
• models_birds.pp: Classes of individuals, captures, and feathers
• models_botany.pp: Classes of botanical taxa
• models_breeding.pp: Classes of nests, nest revisions, and eggs
• models_geo.pp: Classes of gazetteer and POIs
• models_institutions.pp: Classes of institutions
• models_media.pp: Classes of images, audio recordings, and documents
• models_people.pp: Classes of researchers
• models_permits.pp: Classes of permits
• models_projects.pp: Classes of projects
• models_sampling.pp: Classes of methods, expeditions, surveys, sampling plots, specimens, and related data
• models_sightings.pp: Classes of sightings
• models_specimens.pp: Classes of specimens
• models_taxonomy.pp: Classes of ornithological taxa
• models_users.pp: Classes of users
• models_xmobile.pp: Classes of Xolmis Mobile records

UI and Form Architecture

The interface follows a consistent layout using native Lazarus components:

• Main Form: Navigation bar, view panels, and modal dialogs
• Entity Forms: Pop-up windows for record creation and editing
• Viewer Panels: Modular panels for data browsing with filters and tabbed views

Each form is built around event-driven patterns, triggering callbacks to modules via observer patterns where applicable.

Module Interactions

Modules communicate through:

• Centralized data bus for shared records (such as user identity, project config)
• Schema definitions used across forms and exporters
• Utility methods and enums accessible via models/model_*.pp

This keeps cross-module logic minimal and ensures easy debugging and scaling.

Utilities and Helpers

Common functions live in the /source/utils directory:

• utils_global.pp: Global variables, enums and classes
• utils_autoupdate.pp: Xolmis autoupdate methods
• utils_backup.pp: Backup and restore routines
• utils_conversions.pp: Functions to convert strings, date and time, numerals etc.
• utils_debug.pp: Utilities to debug Xolmis
• utils_dialogs.pp: Methods to call many types of dialogs
• utils_editdialogs.pp: Methods to call edit dialogs
• utils_finddialogs.pp: Methods to call find dialogs
• utils_fullnames.pp: Functions to create full names for many types of records
• utils_gis.pp: Utilities for geographical coordinates, mostly conversions
• utils_graphics.pp: Utilities for graphical user interface
• utils_locale.pp: Library of resource strings that can be translated
• utils_math.pp: Mathematical and statistical methods
• utils_permissions.pp: Deal with user permissions
• utils_print.pp: Utilities for printing
• utils_system.pp: Operating system routines
• utils_taxonomy.pp: Taxonomy related functions
• utils_themes.pp: Colors and theming
• utils_validations.pp: Field-level and logical validation utilities

Database related functions live in /source/data directory:

• data_management.pp: Database creation and upgrade methods
• data_types.pp: Database related classes and enums
• data_blobs.pp: Methods related to BLOB fields
• data_columns.pp: Display name translation and calculated summary of fields
• data_consts.pp: Table and field name constants
• data_count.pp: Record count methods
• data_filters.pp: Methods related to data filtering
• data_getvalue.pp: Methods to get specific values from database
• data_search.pp: Default SQL query for each table
• data_setparam.pp: Methods to set SQL query parameters

File I/O, import and export functions live in /source/io directory:

• io_core.pp: Import and export related classes and enums
• io_csv.pp: CSV file import and export classes and routines
• io_json.pp: JSON file import and export classes and routines
• io_ods.pp: ODS file import and export classes and routines
• io_xlsx.pp: XLSX file import and export classes and routines
• io_xml.pp: XML file import and export classes and routines
• io_dbf.pp: DBF file import classes and routines
• io_ebird_csv.pp: eBird Record Format CSV file import and export classes and routines
• io_banding_csv.pp: Banding CSV files import and export classes and routines
• io_nesting_csv.pp: Nesting CSV files import and export classes and routines

These files are lightweight and reused across modules, promoting DRY principles.

Next Steps for Developers

• Explore the Modules Directory: Start with one module — e.g., models_specimens.pp — to learn the architecture.
• Review Shared Schemas: See how entities are represented consistently across UI, database, and export layers.
• Extend a Module: Try adding a new field or validator to a domain table and observe how changes propagate.