SPOT Platform Documentation¶

SPOT (Spear-Phishing Overwatching Tool) is an open-source email security platform that classifies incoming messages as phishing or clean and helps the operator act on the verdict. This site is the documentation for the platform itself: how it works, how to use it, and how to operate it.

Where to start¶

If this is your first encounter with SPOT, the concepts pages explain what the platform does and how the pieces fit together without expecting you to know its internals. Read them in order or jump to the one that answers your question:

• How SPOT works — the journey of one email through SPOT, from arrival to verdict.
• Plugins — analyzers, context providers, and mail retrievers.
• Workflows — the policies that decide which analyzers run and how their verdicts combine.
• Knowledge store — the shared memory of organisational facts that analyzers consult.

For a guided walk through the operator UI, see the Web UI section.

Guides¶

When you know what SPOT is, the guides cover the recurring tasks:

• Admin guide — deployment, configuration, backups, scaling.
• Core developer guide — contributing to the SPOT platform.
• Plugin developer guide — building or contributing to plugins.
• Knowledge store guide — operating the knowledge store.
• Context providers guide — what context providers are and how to use them.

The operator's day-to-day playbook (reviewing flagged messages, adjusting workflows, installing plugins through the dashboard) lives in the Web UI section.

Getting started¶

To install SPOT and run a first analysis end-to-end, start with:

• Quickstart — bring the platform up on a fresh machine.
• First analysis — submit your first email and read the verdict.

Reference¶

• API reference — every HTTP endpoint exposed by the platform.
• Configuration reference — every setting in spot.yaml and the .env file.
• Environment variables — what each variable controls.
• Database schema — tables, columns, and retention policies.
• Architecture decisions — the ADRs that record why the platform is shaped the way it is.

Operations¶

• Environments — dev, test, and prod modes.
• Testing — how to run the test suites.
• CI/CD — how the platform is built and released.
• Benchmarking — load- and latency-testing the platform.

Need help?¶

• Report issues on Codeberg.
• The full documentation site is at https://spot-project.codeberg.page/documentation/.