================== Developer Overview ================== This document provides a high-level overview of the main modules in the ``overleaf_fs`` package and their responsibilities. It is intended as a starting point for new contributors and as a quick reminder for future maintenance and refactoring work. Package layout ============== The package is organized into a small core layer (data model, config, persistence, scraping, and index construction) and a GUI layer (Qt-based desktop application), plus minimal top-level entry points. Top-level package (``overleaf_fs``) ----------------------------------- * ``overleaf_fs/__init__.py`` Lightweight package initializer. Currently provides package metadata (such as the version) and a convenient place for any future top-level imports or helpers that should be exposed as ``overleaf_fs.*``. * ``overleaf_fs/app.py`` GUI application bootstrap. Creates the Qt application object, constructs the main window, and starts the event loop. This is the canonical way to launch the desktop GUI from Python code. * ``overleaf_fs/cli.py`` Command-line entry points. Provides the functions that are wired up by packaging (e.g. console scripts) and can be extended with additional subcommands for scripting or headless utilities. Core layer (``overleaf_fs.core``) --------------------------------- The core layer contains configuration handling, persistent metadata storage, the data model, and logic for connecting Overleaf's project information with local directory-structure data. * ``overleaf_fs/core/__init__.py`` Marks the ``core`` subpackage and may re-export a small number of public helpers in the future. At the moment it is intentionally minimal to keep the public surface explicit. * ``overleaf_fs/core/config.py`` Central configuration and path logic. - Knows where the profile root directory lives on disk. - Defines the canonical filenames for the per-profile JSON files: * projects-info JSON file: ``overleaf_projects_info.json`` * directory-structure JSON file: ``local_directory_structure.json`` * profile-config JSON file: ``profile_config.json`` - Provides helpers such as ``get_active_profile_data_dir()``, ``get_projects_info_path()``, and ``get_directory_structure_path()`` so that other modules never hard-code paths or filenames. - Contains ``FILE_FORMAT_VERSION`` and related constants that control the on-disk layout. * ``overleaf_fs/core/metadata_store.py`` Persistence for *local* directory-structure data. - Defines ``LocalState``, which holds: * ``folders``: explicit list of known folder paths (e.g. ``"CT"``, ``"Teaching/2025"``), used to persist empty folders. * ``projects``: mapping from project id to ``ProjectLocal`` (folder, notes, pinned/hidden flags). - Implements ``load_directory_structure()`` and ``save_directory_structure()`` which read/write the directory-structure JSON file located at ``get_directory_structure_path()``. - Does **not** know about the Overleaf-side projects-info JSON; it is strictly responsible for local-only metadata. * ``overleaf_fs/core/models.py`` Core data model definitions. - ``ProjectRemote``: Overleaf-side fields for a project, as stored in the projects-info JSON file. - ``ProjectLocal``: local-only directory-structure fields for a project, as stored in the directory-structure JSON file. - ``ProjectRecord``: in-memory combination of ``remote`` and ``local`` data for a single project id. - ``ProjectsIndex``: type alias for the mapping ``Dict[str, ProjectRecord]`` that represents all known projects. * ``overleaf_fs/core/overleaf_scraper.py`` Scraping and synchronization with the Overleaf project dashboard. - Builds an authenticated HTTP session from a browser Cookie header. - Scrapes the Overleaf projects dashboard and converts the results to ``OverleafProjectDTO`` objects. - Writes the projects-info JSON file at ``get_projects_info_path()``. - Exposes an entry point used by the GUI to refresh the cached projects-info data for the active profile. * ``overleaf_fs/core/project_index.py`` Construction of the in-memory projects index. - Loads the projects-info JSON (remote metadata) and the directory-structure JSON (local metadata). - Merges these two sources into a ``ProjectsIndex`` mapping from project id to ``ProjectRecord``. - The merge is keyed by Overleaf project id: * ``ProjectRecord.remote`` is overwritten on each refresh from Overleaf. * ``ProjectRecord.local`` is preserved across refreshes and reflects the user’s local organization and annotations. * ``overleaf_fs/core/profiles.py`` Profile management and profile-level storage configuration. - Defines ``ProfileInfo`` and helpers for discovering, creating, renaming, and deleting profiles under the profile root directory. - Stores and retrieves the active profile via ``active_profile.json``. - Provides ``get_active_profile_info()`` and related helpers used at startup to ensure that an active profile always exists. - Encapsulates all logic for paths and filenames inside profile-level subdirectories. GUI layer (``overleaf_fs.gui``) ------------------------------- The GUI layer provides the Qt-based desktop application. It is split into a main window, a login dialog, and supporting widgets plus their models. * ``overleaf_fs/gui/__init__.py`` Marks the ``gui`` subpackage. Kept minimal so that importing the GUI layer is explicit and does not accidentally pull in Qt when used as a library. * ``overleaf_fs/gui/main_window.py`` The main application window and high-level GUI controller. - Owns the project tree (folders) and project table widgets. - Initializes the profile subsystem: ensures a valid profile root exists and calls ``get_active_profile_info()`` so that an active profile is always available on startup. - Connects user actions (selection, drag-and-drop, sync buttons) to core-layer operations such as ``load_projects_index()``, ``load_directory_structure()``, and Overleaf refresh calls. - Implements external-change detection for the metadata JSON files and offers to reload when they change on disk. * ``overleaf_fs/gui/profile_manager.py`` Profile selection and management dialog. - Allows the user to select, create, rename, delete, or open a profile. - Provides a "Move…" action to relocate the entire profile-storage folder, using shared UI helpers. - Ensures that the current active profile is restored when the user presses Cancel. - Delegates disk‑level path changes to the core config layer. * ``overleaf_fs/gui/profile_root_ui.py`` Shared UI helpers for selecting or relocating the profile root directory. - Presents the explanatory message shown when choosing a profile storage folder. - Configures a non-native directory chooser dialog with cloud-storage sidebar entries. - Provides ``choose_profile_root_directory()`` for both first‑run setup and the profile manager's Move… flow. - Includes ``looks_like_profile_root()`` which detects whether a folder already contains OverleafFS profile data. * ``overleaf_fs/gui/overleaf_login.py`` Login / cookie-entry dialog. - Provides a small dialog where the user can paste a browser Cookie header used to authenticate with Overleaf. - Hands the Cookie header off to ``overleaf_scraper`` to refresh the projects-info JSON. - Can be extended in the future to support richer authentication flows. * ``overleaf_fs/gui/project_table.py`` Project table widget and related utilities. - Contains the Qt widget that displays the list of projects in tabular form. - Handles interactions such as row selection and double-click behavior, delegating data access to the table model. * ``overleaf_fs/gui/project_table_model.py`` Qt table model for projects. - Implements ``QAbstractTableModel`` (or a subclass) backed by the ``ProjectsIndex``. - Provides the data needed by the project table widget: project name, owner, folder, last modified time, pinned/hidden flags, etc. - Encapsulates sorting and column configuration logic. * ``overleaf_fs/gui/project_tree.py`` Project folder tree widget. - Represents the folder hierarchy (Home, subfolders, pinned/archived views) as a Qt tree widget. - Supports folder selection, expansion/collapse, and drag-and-drop of projects between folders. - Works in concert with the main window to keep the tree in sync with the current directory-structure metadata. Notes for future maintenance ============================ - Keep file and directory names centralized in ``config.py`` so other modules do not hard-code paths or filenames. - Treat ``metadata_store`` as the single source of truth for the directory-structure JSON file, and ``project_index`` as the place where remote (Overleaf) and local (directory-structure) metadata are merged. - When evolving the on-disk format, update ``FILE_FORMAT_VERSION`` and document any migration steps here so that future refactors remain understandable. - Keep profile-handling logic centralized in ``profiles.py`` and route all profile‑root selection through ``profile_root_ui.py`` to avoid duplicating UI flows.