# stevecode21/opencats_lawrence architecture

> Architecture diagram of the GitHub repository stevecode21/opencats_lawrence, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/stevecode21/opencats_lawrence
- Repository: https://github.com/stevecode21/opencats_lawrence

## Overview

##### Project type and purpose
- This is a full-stack, monolithic PHP web application (OpenCATS) for applicant tracking.
- It exposes both traditional page views (via modules/*.tpl and UI PHP classes) and an AJAX API (ajax/*.php) to drive dynamic features (search, inline edits, lookups).
- It includes CLI/queue components (QueueCLI.php, modules/queue with tasks), scheduled scripts (scripts/…), and uses Sphinx for full-text search, MySQL for persistence, and filesystem storage for attachments.

##### File structure
Top-level components:
- web root: index.php, ajax/, modules/, js/, css/, attachments/
- core libraries and business logic: lib/
- modern PHP domain model & tests: src/OpenCATS/Entity + src/OpenCATS/UI + tests (unit & integration) + behat tests
- configuration: config.php, composer.json/lock, docker/ (Compose files), .travis.yml, CI scripts
- database schema & upgrades: db/
- search engine integration: lib/sphinx, optional-updates/latest-sphinx-search, scripts/sphinx_*
- background/queue: QueueCLI.php, modules/queue, scripts/…
- utilities & build scripts: scripts/, ci/, rebuild_old_docs.php

##### README for additional insights
- Confirms “free & open source candidate/applicant tracking system.”
- Key features: job posting → candidate application → selection/submission.
- No built-in distributed microservices—single PHP codebase with optional Docker containers for MySQL, PHP, Sphinx.

a. Main components:
1. Client (Browser / JS code / CSS)
2. Web server (Apache/Nginx + PHP-FPM) hosting index.php, ajax endpoints, module/UI classes, lib logic
3. MySQL database (schema in db/)
4. Sphinx search daemon (indices under lib/sphinx/index, config in lib/sphinx/conf)
5. File storage (attachments/ directory)
6. Queue/CLI worker (QueueCLI.php, modules/queue tasks) invoked via cron or CLI
7. External services: SMTP mail server, LDAP directory (lib/LDAP), 3rd-party XML feeds (wsdl/)
8. Docker orchestration (docker-compose.yml): brings up PHP, MySQL, Sphinx for dev/test
9. Test frameworks: SimpleTest (lib/simpletest), Behat (test/features)

b. Relationships and interactions:
- Browser → HTTP requests → Web server → PHP application
- Front-end pages rendered by modules/*.tpl + UI PHP classes
- Dynamic data via AJAX endpoints (ajax/*.php)
- PHP application → MySQL (via lib/DatabaseConnection, lib/DatabaseSearch)
- PHP application → Sphinx API (lib/sphinx/sphinxapi.php) for search queries
- PHP application → filesystem for attachments and temporary files
- PHP application → queue tasks (modules/queue, QueueCLI.php) for background jobs (email reminders, reports)
- CLI/cron → invoke QueueCLI.php → fetch tasks → PHP application logic → update DB/send emails
- Docker Compose network wires PHP, MySQL, Sphinx containers
- CI pipeline (.travis.yml, ci/) runs unit tests (src/OpenCATS/Tests), integration tests, Behat scenarios

c. Architectural patterns and design principles:
- Modular MVC-ish layering: modules/ directory groups UI + templates per domain area (candidates, companies, joborders, etc.).
- Core business logic in lib/ (service classes, utilities)
- Domain model under src/OpenCATS/Entity with repository pattern
- Separation of concerns: UI vs. business logic vs. data access vs. search
- Extension hooks (lib/Hooks) and plugin-style modules for optional components
- Asynchronous background processing via queue/CLI

d. Key technologies, frameworks, libraries:
- PHP (5.6+), Composer for autoloading
- MySQL (InnoDB)
- Sphinx Search
- SimpleTest + Behat for automated testing
- Artichow (PHP charting), FPDF (PDF generation)
- jQuery-style AJAX, custom JS modules in js/
- Docker Compose for development environment

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Presentation Layer"
        browser["Browser"]:::frontend
        js["js/"]:::frontend
        css["CSS Files"]:::frontend
    end

    browser --> js
    browser --> css

    click js "https://github.com/stevecode21/opencats_lawrence/tree/master/js/"
    click css "https://github.com/stevecode21/opencats_lawrence/tree/master/css/"

    subgraph "Web Layer"
        index["index.php"]:::app
        ajax["ajax/*.php"]:::app
        modules["modules/"]:::app
    end

    browser -->|HTTP| index
    browser -->|AJAX| ajax
    index --> modules
    ajax --> modules

    click index "https://github.com/stevecode21/opencats_lawrence/blob/master/index.php"
    click ajax "https://github.com/stevecode21/opencats_lawrence/blob/master/ajax/*.php"
    click modules "https://github.com/stevecode21/opencats_lawrence/tree/master/modules/"

    subgraph "Application Layer"
        lib["lib/"]:::app
        entity1["Company.php"]:::app
        entity2["JobOrder.php"]:::app
        repo1["CompanyRepository.php"]:::app
        repo2["JobOrderRepository.php"]:::app
        ui1["CandidateQuickActionMenu.php"]:::app
        ui2["QuickActionMenu.php"]:::app
    end

    modules --> lib
    modules --> entity1
    modules --> entity2
    lib --> repo1
    lib --> repo2
    lib --> ui1
    lib --> ui2

    click lib "https://github.com/stevecode21/opencats_lawrence/tree/master/lib/"
    click entity1 "https://github.com/stevecode21/opencats_lawrence/blob/master/src/OpenCATS/Entity/Company.php"
    click entity2 "https://github.com/stevecode21/opencats_lawrence/blob/master/src/OpenCATS/Entity/JobOrder.php"
    click repo1 "https://github.com/stevecode21/opencats_lawrence/blob/master/src/OpenCATS/Entity/CompanyRepository.php"
    click repo2 "https://github.com/stevecode21/opencats_lawrence/blob/master/src/OpenCATS/Entity/JobOrderRepository.php"
    click ui1 "https://github.com/stevecode21/opencats_lawrence/blob/master/src/OpenCATS/UI/CandidateQuickActionMenu.php"
    click ui2 "https://github.com/stevecode21/opencats_lawrence/blob/master/src/OpenCATS/UI/QuickActionMenu.php"

    subgraph "Data Layer"
        mysql["MySQL Database"]:::data
        sphinx["Sphinx Search"]:::data
        fs["Filesystem (attachments)"]:::data
    end

    lib --> mysql
    lib --> sphinx
    lib --> fs
    ajax --> mysql

    click mysql "https://github.com/stevecode21/opencats_lawrence/tree/master/db/"
    click sphinx "https://github.com/stevecode21/opencats_lawrence/tree/master/lib/sphinx/"
    click fs "https://github.com/stevecode21/opencats_lawrence/tree/master/attachments/"

    subgraph "Background Worker"
        queuecli["QueueCLI.php"]:::app
        queueMod["modules/queue/"]:::app
    end

    lib --> queuecli
    queuecli --> queueMod

    click queuecli "https://github.com/stevecode21/opencats_lawrence/blob/master/QueueCLI.php"
    click queueMod "https://github.com/stevecode21/opencats_lawrence/tree/master/modules/queue/"

    subgraph "External Services"
        smtp["SMTP Mail Server"]:::external
        ldap["LDAP Directory"]:::external
        wsdl["WSDL Feeds"]:::external
        mailer["Mailer & EmailTemplates"]:::external
    end

    lib --> smtp
    lib --> ldap
    lib --> wsdl
    lib --> mailer

    click ldap "https://github.com/stevecode21/opencats_lawrence/blob/master/lib/LDAP.php"
    click wsdl "https://github.com/stevecode21/opencats_lawrence/tree/master/wsdl/"
    click mailer "https://github.com/stevecode21/opencats_lawrence/blob/master/lib/Mailer.php"

    subgraph "Configuration & Orchestration"
        config["config.php & constants"]:::app
        composer["composer.json/lock"]:::app
        docker["docker/docker-compose.yml"]:::app
        ciCfg[".travis.yml & ci scripts"]:::app
    end

    config --> lib
    composer --> lib
    docker --> lib
    ciCfg --> lib

    click config "https://github.com/stevecode21/opencats_lawrence/blob/master/config.php"
    click composer "https://github.com/stevecode21/opencats_lawrence/blob/master/composer.json"
    click docker "https://github.com/stevecode21/opencats_lawrence/blob/master/docker/docker-compose.yml"
    click ciCfg "https://github.com/stevecode21/opencats_lawrence/blob/master/.travis.yml"

    subgraph "Testing & CI"
        unit["Unit & Integration Tests"]:::app
        behat["Behat Features"]:::app
    end

    ciCfg --> unit
    ciCfg --> behat

    click unit "https://github.com/stevecode21/opencats_lawrence/tree/master/src/OpenCATS/Tests/UnitTests/"
    click behat "https://github.com/stevecode21/opencats_lawrence/tree/master/test/features/"

    classDef frontend fill:#AEC6CF,stroke:#000;
    classDef app fill:#77DD77,stroke:#000;
    classDef data fill:#FFB347,stroke:#000;
    classDef external fill:#D3D3D3,stroke:#000;
```
