# Project Structure

This directory is the root directory of the **Topola Genealogy Viewer** project.
It serves as the central hub containing project configuration, build setup,
dependency management, and the main entry points for development, testing, and
deployment. The actual application source code, assets, and tests are organized
into subdirectories.

## Purpose of this Directory

The root directory orchestrates the project. It contains configuration files for
various tools (Vite, ESLint, Jest, Playwright, TypeScript), metadata about
dependencies (`package.json`), and scripts for common tasks. It glues together
the source code in `src`, the static assets in `public`, and the tests in
`tests`.

## Files in this Directory (Categorized by Role)

Here is an enumeration of the files in this directory, categorized by their role
in the project:

### Application Entry Point

- **[index.html](index.html)**: The main HTML entry point for the application.

### Build & Environment

- **[.env](.env)**: Contains environment variables for the project.
- **[vite.config.mts](vite.config.mts)**: Configuration file for the Vite build
  tool.

### Dependencies & Scripts

- **[package.json](package.json)**: Defines the project's dependencies, scripts,
  version, and other metadata.
- **[package-lock.json](package-lock.json)**: Automatically generated file that
  describes the exact dependency tree that was generated by npm.
- **[deploy-wikitree.sh](deploy-wikitree.sh)**: A shell script used to deploy
  the application files to WikiTree servers using `lftp`.

### Tool Configuration

- **[.eslintrc.js](.eslintrc.js)**: Configuration file for ESLint, used for
  identifying and reporting on patterns in JavaScript/TypeScript code.
- **[.gitignore](.gitignore)**: Specifies files and directories that should be
  ignored by Git.
- **[prettier.config.mjs](prettier.config.mjs)**: Configuration for Prettier
  code formatter.
- **[tsconfig.json](tsconfig.json)**: Configuration file for the TypeScript
  compiler.

### Testing

- **[playwright.config.ts](playwright.config.ts)**: Configuration file for
  Playwright end-to-end testing framework.
- **[playwright.prober.config.ts](playwright.prober.config.ts)**: Separate
  Playwright config for prober (live smoke) tests against deployed URLs.
- **[jest.config.ts](jest.config.ts)**: Configuration file for the Jest testing
  framework used for unit tests.

### Documentation & Assets

- **[README.md](README.md)**: The main project documentation, covering features,
  examples, and usage instructions.
- **[CHANGELOG.md](CHANGELOG.md)**: Records a log of notable changes made to the
  project over time.
- **[docs/README.md](docs/README.md)**: Registry for system design files
  describing containerization, AI protocol interfaces, Playwright integration,
  and screenshot testing.
- **[LICENSE](LICENSE)**: The license file for the project (Apache License 2.0).
- **[screenshot.png](screenshot.png)**: An image showing a screenshot of the
  application, used in the README.md.

## Subdirectories Overview

Based on the documentation in the subdirectories, here is a high-level overview
of the project's structure:

- **[docs](docs)**: High-level technical and architectural design documents.
- **[src](src)**: The core of the application.
  - **[datasource](src/datasource)**: Handles loading and transforming
    genealogical data from various sources (files, URLs, WikiTree).
  - **[menu](src/menu)**: Contains navigation and menu components.
  - **[sidepanel](src/sidepanel)**: Implements the side panel for details and
    configuration.
  - **[translations](src/translations)**: Holds localization JSON files.
  - **[util](src/util)**: Common utilities for dates, analytics, and data
    processing.
- **[public](public)**: Contains static assets (like the favicon) served
  directly at the root path.
- **[tests](tests)**: Contains end-to-end tests.
  - **[tests/probers](tests/probers)**: Live smoke tests (probers) that run
    against deployed URLs and external services.
