Project structure

This page is for a developer who has just cloned the repository. It explains what every folder is, how a log line and a beacon hit travel through the code, how the panel is put together, and which files to open for the most common changes. It stays high level on purpose; the linked pages and SPEC.md go deeper.

Loghound is plain PHP 8.1+ with no Composer packages, no npm and no build step. It is really four programs sharing one library in src/:

Everything Loghound learns lives in two Opensolr indexes it provisions for you; small working state (file positions, open visits, staged beacon rows) lives in a local SQLite file.

Every command and option is on the command reference; the services and timers on running it.

Top-level classes

Subfolders

• src/Enrich/ — adds context to a request: Geo (country and timezone), Asn (network, netname, reverse DNS), Ua (browser and declared bots).
• src/Score/ — detection: Signals extracts the evidence, Rules holds the weighted rules and the verdict, Attacks spots hostile requests.
• src/Panel/ — the web interface: one controller class per view (Overview, Bots, Fingerprints, Sessions, Seo...), plus Layout (routes, navigation, page chrome), Gateway (the panel's only route to Solr), Query, Facets, Sorting, Paging and the long-running Jobs.
• src/Setup/ — installing: the browser Installer, detection and requirement checks, index provisioning and schema sync, resumable jobs, reset and teardown.
• src/Auth/ — panel sign-in extras: two-factor codes, the QR code for the authenticator, “stay signed in”.
• src/Live/ — the live view, reading logs as they are written without touching ingest.
• src/Geo/Countries.php and src/Beacon/Doc.php — the one country table, and the one description of the beacon shown wherever it is documented.

A log line, into the hits index

1. Tail reads the new line and remembers its position in State.
2. LogFormat and Parser turn it into a request with named fields; lines that do not parse are sampled to a file.
3. Enrich\Geo, Enrich\Asn and Score\Attacks add context; Exclusions and AttackPatterns apply the operator's rules.
4. Sessionizer attaches the request to a visit (same network and browser, 30 minutes of inactivity closes it).
5. Solr::addDocs() writes the batch into the hits index, after Quota confirms there is room.

A visit, into the sessions index

1. loghound-score finds visits that went idle.
2. Beacon::mergeIntoSession() adds what the browser reported.
3. Score\Signals gathers the evidence and Score\Rules computes the score, the verdict and its reasons.
4. The visit document, and the daily rollups, are written into the sessions index.

A beacon hit

1. b.js in the visitor's browser posts to collect.php.
2. The collector checks the signed token, size, origin and allowed hosts, rate-limits, stages the row in SQLite, and always answers 204. It never touches Solr.
3. The next scorer run merges the staged row into its visit.

A panel page

1. public/index.php sets security headers, loads the configuration, sends first-time visitors to the installer, and checks sign-in and CSRF.
2. The view named in ?v= is looked up in Layout::routes(); its controller draws the page frame without querying Solr.
3. Each card then asks the server for its own data (?api=); the controller answers through Gateway, Cache and Solr, so one slow card never blocks the others.
4. On the browser side, public/assets/js/app.js loads the matching module from public/assets/js/views/, which fills its cards with loadCard() from core.js.

• The configuration is a PHP array in config/loghound.php, mode 0640, written by Config::save(). Its sections are documented in config/loghound.example.php and on settings.
• Secrets — the Opensolr API key, the beacon secret, the IP salt, the panel password hash and the two-factor secret — live in that file; sign-in state lives in files under var/ with mode 0600. None of them is ever committed.
• Working state is var/state.db (SQLite) and a few status files, also under var/.

solr/hits/conf holds one document per request; solr/sessions/conf one per visit plus daily rollups. Every field is explained on the Solr schema. The schema rules are strict: fields are not stored unless needed, string fields carry no norms, there is no catch-all field, and an undeclared field is silently ignored.

1. Change solr/hits/conf/schema.xml or solr/sessions/conf/schema.xml.
2. Run bin/loghound-schema --check to see what differs from the live index.
3. Run bin/loghound-schema --apply to upload it. Operators do the same after upgrading.

• A test file is tests/test_<name>.php returning named closures; the runner finds it by itself.
• Versions are the headings in CHANGELOG.md and the matching git tags.

They are written in CONTRIBUTING.md; in short:

• No dependencies: no Composer packages, no npm, no build step, no CDN.
• Security first: escape at output, user text to Solr only as bound parameters, allowlisted field names, safe paths, CSRF on every change, no secrets in code.
• Honesty: an unknown number is absent, never zero; every verdict carries its reasons; limitations are documented.
• Style: PSR-12, four spaces, single quotes, strict types, and the comment rules in CONTRIBUTING.md.
• One change per pull request, with its documentation and a changelog entry.