# CiviGO.eu

Премиум PHP 8.3 MVC платформа за български граждани: сигнали, AI асистент, ЗДОИ заявления, петиции, институции, карта, документи, QR услуги, статистики, прозрачност и админ панел.

## Stack

- PHP 8.3, MySQL, MVC
- Bootstrap 5, Bootstrap Icons, AJAX, JavaScript
- Leaflet.js + OpenStreetMap
- Chart.js
- PHPMailer, Dompdf, Endroid QR Code ready through Composer
- CSRF, session hardening, prepared statements, session rate limiting
- OpenAI-compatible AI client through `OPENAI_BASE_URL`, `OPENAI_API_KEY`, `OPENAI_MODEL`
- Institution delivery workflow: email delivery evidence, SSeV/portal handoff, message-id, incoming-number tracking
- Dark mode, PWA manifest, service worker, SEO meta baseline

## Quick Start

```bash
cd outputs/civigo
cp .env.example .env
php -S 127.0.0.1:8088 -t public
```

Open `http://127.0.0.1:8088`.

The app runs with demo data when MySQL is not configured. To enable MySQL:

```bash
mysql -u root -p -e "CREATE DATABASE civigo CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;"
mysql --default-character-set=utf8mb4 -u root -p civigo < database/schema.sql
mysql --default-character-set=utf8mb4 -u root -p civigo < database/seed.sql
```

Then update `.env` with DB credentials.

## Composer Packages

The project is designed to work without installing dependencies for the demo. For production features:

```bash
composer install
```

This enables PHPMailer, Dompdf and real QR generation through Composer packages.

## Main Routes

- `/` - landing page
- `/dashboard` - user dashboard
- `/reports/new` - report generator
- `/assistant` - AI assistant
- `/zdoi` - ZДОИ generator
- `/petitions` - petition generator
- `/institutions` - institution database
- `/map` - interactive map
- `/tracking` - status tracking
- `/handbook` - citizen handbook
- `/generators` - document generators
- `/qr-library` - QR library
- `/statistics` - statistics
- `/transparency` - transparency dashboard
- `/admin` - admin panel

## Security Notes

- All POST actions validate CSRF tokens.
- Repositories use PDO prepared statements when MySQL is available.
- Session cookies are HTTP-only with SameSite=Lax.
- Rate limiting is included in session form for demo and has a `rate_limits` table ready for production.
- Public transparency language is objective and data-derived.

## Delivery and Feedback Model

CiviGO can provide proof of sending and a strict follow-up workflow, but no private platform can honestly guarantee that an institution employee reads a normal email. The strongest production channel is secure e-delivery or the institution's official portal, because it can provide stronger evidence of sending/receiving and usually produces an incoming number.

Implemented flow:

1. The report is saved in `reports`.
2. An official document body is generated.
3. `InstitutionDeliveryService` sends by email or prepares secure SSeV/portal handoff.
4. Every attempt is stored in `report_deliveries` with channel, recipient, status, message-id and evidence JSON.
5. The user should add an incoming number when the institution/portal returns one.
6. Deadline reminders and escalations can be built on `deadline_at`, `incoming_number`, `report_events` and `report_deliveries`.

Recommended production setup:

- Use SPF, DKIM and DMARC for the sending domain.
- Use a real SMTP provider with bounce webhooks.
- Prefer SSeV/official portals where possible.
- Require incoming number for "received" status.
- Send reminders before deadline and create appeal/ZDOI templates after missed deadlines.

## Next Production Steps

1. Add real authentication persistence, password reset tokens and Google OAuth client credentials.
2. Connect file upload scanning and private object storage.
3. Replace demo repository fallbacks with full CRUD screens.
4. Add queue workers for email, PDF generation, reminders and AI tasks.
5. Add PHPUnit/Pest tests for controllers, repositories and document generators.
