System architecture
Introduction
tirreno is a PHP/PostgreSQL application using Fat-Free Framework (F3). Lightweight MVC for safety analytics, security analytics and threat detection.
Overview
┌──────────┐ request ┌─────────────────┐ POST /sensor/ ┌─────────────────┐
│ User │ ─────────────────▶ │ Your App │ ────────────────────────▶│ tirreno │
└──────────┘ │ (allow/deny) │◀──────────────────────── │ • Risk scoring │
└─────────────────┘ response │ • Rule engine │
│ • Blacklist │
└─────────────────┘ |
Your application sends user events (logins, registrations, page views, field changes) to tirreno. tirreno analyzes the events, calculates risk scores, and can automatically blacklist suspicious users. Your app can query the blacklist API to block bad actors in real-time.
Technology stack
Core dependencies (composer.json):
| Dependency | What it does |
|---|
| bcosca/fatfree-core | Fat-Free Framework (F3) |
| matomo/device-detector | Device/browser/OS detection |
| ruler/ruler | Rules engine |
Dev tools: phpstan (static analysis), php_codesniffer (style)
System requirements
- PHP 8.0–8.3 with PDO_PGSQL, cURL, mbstring
- PostgreSQL 12+
- Apache with mod_rewrite
Hardware: 512 MB RAM for PostgreSQL (4 GB recommended), ~3 GB storage per 1M events.
Directory structure
tirreno/
│
├── .github/ # GitHub configuration
│ ├── workflows/ # CI/CD workflows
│ │ └── ci.yml # Continuous integration
│ └── actions/ # Custom GitHub actions
│
├── tests/ # Test suites
│ ├── Unit/ # Unit tests
│ └── Support/ # Test support files
│
├── app/ # Application code
│ ├── Assets/ # Rule base classes
│ │ └── Rule.php # Abstract Rule class
│ │
│ ├── Controllers/ # Request handlers
│ │ ├── Admin/ # Admin panel controllers
│ │ │ ├── Base/ # Base controller classes
│ │ │ ├── Events/ # Events module
│ │ │ ├── Rules/ # Rules module
│ │ │ ├── Users/ # Users module
│ │ │ └── ... # Other admin modules
│ │ ├── Api/ # API controllers
│ │ │ ├── Blacklist.php # Blacklist API
│ │ │ └── Endpoint.php # API endpoint handler
│ │ ├── Pages/ # Page controllers
│ │ │ ├── Login.php
│ │ │ ├── Signup.php
│ │ │ └── ...
│ │ ├── Cron.php # Cron controller
│ │ └── Navigation.php # Navigation controller
│ │
│ ├── Crons/ # Background job handlers
│ │ ├── Base.php # Base cron class
│ │ ├── BatchedNewEvents.php
│ │ ├── EnrichmentQueueHandler.php
│ │ ├── RiskScoreQueueHandler.php
│ │ └── ... # Other cron jobs
│ │
│ ├── Dictionary/ # Internationalization (i18n)
│ │ └── en/ # English translations
│ │ ├── Pages/ # Page-specific translations
│ │ ├── Parts/ # Component translations
│ │ └── All.php # Combined translations
│ │
│ ├── Interfaces/ # PHP interfaces
│ │ ├── ApiKeyAccessAuthorizationInterface.php
│ │ ├── ApiKeyAccountAccessAuthorizationInterface.php
│ │ └── FraudFlagUpdaterInterface.php
│ │
│ ├── Models/ # Database models (extend BaseSql)
│ │ ├── BaseSql.php # Base class with execQuery()
│ │ ├── Device.php # Device/user-agent model
│ │ ├── Grid/ # Grid data models
│ │ ├── Chart/ # Chart data models
│ │ ├── Enrichment/ # Enrichment models
│ │ └── ... # Other models
│ │
│ ├── Updates/ # Database migration handlers
│ │
│ ├── Utils/ # Utility classes
│ │ ├── ApiKeys.php # API key utilities
│ │ ├── Constants.php # Application constants
│ │ ├── Logger.php # Logging utilities
│ │ ├── Rules.php # Rule utilities
│ │ └── ... # Other utilities
│ │
│ └── Views/ # View helpers
│
├── assets/ # Static assets and rules
│ ├── rules/ # Rules engine
│ │ ├── core/ # Core rule definitions
│ │ └── custom/ # Custom rule definitions
│ ├── lists/ # Suspicious pattern lists
│ │ ├── url.php # URL attack patterns
│ │ ├── user-agent.php # User agent patterns
│ │ ├── email.php # Email patterns
│ │ └── file-extensions.php # File extension categories
│ ├── logs/ # Application logs
│ └── ... # CSS, images
│
├── config/ # Configuration files
│ ├── config.ini # Main configuration
│ ├── routes.ini # Route definitions
│ ├── apiEndpoints.ini # API endpoint definitions
│ ├── crons.ini # Cron job configuration
│ └── local/ # Local overrides
│
├── install/ # Web-based installation wizard
│ └── index.php # DELETE AFTER INSTALLATION
│
├── libs/ # Third-party libraries (vendor)
│
├── sensor/ # API endpoint for event ingestion
│
├── tmp/ # Temporary files, cache
│
├── ui/ # Frontend UI
│ ├── css/ # Stylesheets
│ ├── images/ # Static images
│ │ ├── icons/
│ │ └── flags/
│ ├── js/ # JavaScript files
│ │ ├── endpoints/ # Page entry points
│ │ ├── pages/ # Page controllers
│ │ │ ├── Base.js # Base page class
│ │ │ ├── Ips.js # IPs page
│ │ │ ├── Events.js # Events page
│ │ │ └── ... # Other pages
│ │ ├── parts/ # Reusable components
│ │ │ ├── grid/ # Data grid components
│ │ │ ├── chart/ # Chart components (uPlot)
│ │ │ ├── panel/ # Detail panel components
│ │ │ ├── choices/ # Filter components (Choices.js)
│ │ │ ├── details/ # Detail view components
│ │ │ ├── popup/ # Popup/modal components
│ │ │ ├── utils/ # Utility modules
│ │ │ │ ├── Constants.js
│ │ │ │ ├── String.js
│ │ │ │ └── Date.js
│ │ │ └── ... # Other components
│ │ └── vendor/ # Third-party JS libraries
│ │ ├── jquery-3.6.0/
│ │ ├── datatables-2.3.2/
│ │ ├── uPlot-1.6.18/
│ │ ├── choices-10.2.0/
│ │ ├── jvectormap-2.0.5/
│ │ ├── tooltipster-master-4.2.8/
│ │ ├── accept-language-parser-1.5.0/
│ │ └── devbridge-jquery-autocomplete-1.5.0/
│ └── templates/ # HTML templates
│ ├── layout.html # Base layout
│ ├── pages/ # Page templates
│ │ ├── admin/ # Admin page templates
│ │ │ ├── events.html
│ │ │ ├── ip.html
│ │ │ ├── users.html
│ │ │ └── ...
│ │ ├── login.html
│ │ ├── signup.html
│ │ └── ...
│ ├── parts/ # Component templates
│ │ ├── headerAdmin.html
│ │ ├── footerAdmin.html
│ │ ├── leftMenu.html
│ │ ├── notification.html
│ │ ├── forms/
│ │ ├── panel/
│ │ ├── tables/
│ │ ├── widgets/
│ │ └── choices/
│ └── snippets/ # Code snippets (PHP, Python, etc.)
│
├── index.php # Application entry point
├── .htaccess # Apache URL rewriting rules
├── .profile # Environment profile
├── composer.json # PHP dependencies
├── composer.lock # Locked dependency versions
├── cron.json # Cron job definitions
├── phpcs.xml # PHP CodeSniffer configuration
├── eslint.config.js # JavaScript linting configuration
│
├── AUTHORS.md # Project contributors
├── CHANGELOG.md # Version history
├── CODE_OF_CONDUCT.md # Community guidelines
├── LICENSE # AGPL-3.0 license
├── LEGALNOTICE.md # Legal notices
├── README.md # Project overview
├── RELEASE_NOTES.md # Release notes
├── SECURITY.md # Security policy
├── FILE_ID.DIZ # BBS-style file description
└── robots.txt # Search engine directives |
________________________________________________________________________________