{"id":48686294,"url":"https://github.com/manziosee/auditshield","last_synced_at":"2026-04-11T04:14:39.382Z","repository":{"id":341853997,"uuid":"1165943257","full_name":"manziosee/auditshield","owner":"manziosee","description":"Keep your business audit-ready  anywhere in the world. Manage employees, encrypted documents, payroll, and regulatory obligations in one secure multi-tenant SaaS.","archived":false,"fork":false,"pushed_at":"2026-03-18T19:39:49.000Z","size":606,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-19T08:47:26.624Z","etag":null,"topics":["angular","angular-material","apollo-angular","apollographql","celery","django-rest-framework","fernet-encryption","jwt-authentication","postgresql","pymupdf","redis","scss","strawberry-graphql","tesseract","typescript","weasyprint"],"latest_commit_sha":null,"homepage":"https://auditshield-ten.vercel.app","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/manziosee.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-24T17:57:51.000Z","updated_at":"2026-03-18T19:39:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/manziosee/auditshield","commit_stats":null,"previous_names":["manziosee/auditshield"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/manziosee/auditshield","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manziosee%2Fauditshield","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manziosee%2Fauditshield/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manziosee%2Fauditshield/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manziosee%2Fauditshield/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/manziosee","download_url":"https://codeload.github.com/manziosee/auditshield/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/manziosee%2Fauditshield/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31668187,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-10T17:19:37.612Z","status":"online","status_checked_at":"2026-04-11T02:00:05.776Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["angular","angular-material","apollo-angular","apollographql","celery","django-rest-framework","fernet-encryption","jwt-authentication","postgresql","pymupdf","redis","scss","strawberry-graphql","tesseract","typescript","weasyprint"],"created_at":"2026-04-11T04:14:36.039Z","updated_at":"2026-04-11T04:14:39.366Z","avatar_url":"https://github.com/manziosee.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e\n\n\u003cbr/\u003e\n\n\u003cimg src=\"frontend/public/logo.svg\" width=\"110\" height=\"110\" alt=\"AuditShield Logo\"\u003e\n\n\u003cbr/\u003e\n\u003cbr/\u003e\n\n# 🛡️ AuditShield\n\n### **The Global SME Compliance Platform**\n\n\u003e _Keep your business audit-ready — anywhere in the world._\n\u003e Manage employees, encrypted documents, payroll, and regulatory obligations in one secure multi-tenant SaaS.\n\n\u003cbr/\u003e\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Deployed on Fly.io](https://img.shields.io/badge/Deployed%20on-Fly.io-8b5cf6?logo=flydotio\u0026logoColor=white)](https://fly.io)\n\n\u003cbr/\u003e\n\n---\n\n### 🔧 Built With\n\n\u003cbr/\u003e\n\n**Backend**\n\n![Python](https://img.shields.io/badge/Python_3.12-3776AB?style=for-the-badge\u0026logo=python\u0026logoColor=white)\n![Django](https://img.shields.io/badge/Django_5-092E20?style=for-the-badge\u0026logo=django\u0026logoColor=white)\n![DRF](https://img.shields.io/badge/Django_REST_Framework-a30000?style=for-the-badge\u0026logo=django\u0026logoColor=white)\n![GraphQL](https://img.shields.io/badge/Strawberry_GraphQL-E10098?style=for-the-badge\u0026logo=graphql\u0026logoColor=white)\n\n**Database \u0026 Cache**\n\n![PostgreSQL](https://img.shields.io/badge/PostgreSQL_16-4169E1?style=for-the-badge\u0026logo=postgresql\u0026logoColor=white)\n![SQLite](https://img.shields.io/badge/SQLite-003B57?style=for-the-badge\u0026logo=sqlite\u0026logoColor=white)\n![Redis](https://img.shields.io/badge/Redis_7-DC382D?style=for-the-badge\u0026logo=redis\u0026logoColor=white)\n![Celery](https://img.shields.io/badge/Celery-37814A?style=for-the-badge\u0026logo=celery\u0026logoColor=white)\n\n**Frontend**\n\n![Angular](https://img.shields.io/badge/Angular_18-DD0031?style=for-the-badge\u0026logo=angular\u0026logoColor=white)\n![TypeScript](https://img.shields.io/badge/TypeScript_5-3178C6?style=for-the-badge\u0026logo=typescript\u0026logoColor=white)\n![Angular Material](https://img.shields.io/badge/Angular_Material-757575?style=for-the-badge\u0026logo=materialdesign\u0026logoColor=white)\n![Apollo](https://img.shields.io/badge/Apollo_Client-311C87?style=for-the-badge\u0026logo=apollographql\u0026logoColor=white)\n\n**Infrastructure**\n\n![Docker](https://img.shields.io/badge/Docker-2496ED?style=for-the-badge\u0026logo=docker\u0026logoColor=white)\n![Nginx](https://img.shields.io/badge/Nginx-009639?style=for-the-badge\u0026logo=nginx\u0026logoColor=white)\n![GitHub Actions](https://img.shields.io/badge/GitHub_Actions-2088FF?style=for-the-badge\u0026logo=githubactions\u0026logoColor=white)\n![Fly.io](https://img.shields.io/badge/Fly.io-8b5cf6?style=for-the-badge\u0026logo=flydotio\u0026logoColor=white)\n\n\u003cbr/\u003e\n\n---\n\n\u003c/div\u003e\n\n## What is AuditShield?\n\n**AuditShield** is a **multi-tenant SaaS compliance platform** built for small and medium enterprises (SMEs) operating across multiple countries. It centralises everything an SME needs to stay audit-ready:\n\n- 📋 **Employee records** — full lifecycle management with department hierarchy\n- 🔒 **Encrypted document vault** — AES-128 Fernet encryption at rest, OCR text extraction, expiry alerts\n- ✅ **Compliance tracker** — tax, social security, and labour law obligations mapped to global authorities\n- 💰 **Payroll engine** — country-specific tax rules, payroll runs, and payslip generation\n- 📄 **PDF report generation** — async via Celery + WeasyPrint, download when ready\n- 🌍 **Multi-country** — 16+ countries, 17+ currencies, global authority mapping\n- 🔍 **Immutable audit trail** — every write recorded automatically by middleware\n- 🔔 **Notifications** — in-app + email with unread badge and mark-all-read\n- 🔗 **Dual API** — REST (DRF + Swagger) **and** GraphQL (Strawberry + Apollo)\n\nEvery company is a **fully isolated tenant** with UUID-keyed records and scoped row-level queries. No data leaks across tenants — ever.\n\n---\n\n## Table of Contents\n\n- [Features](#features)\n- [Innovation Features](#innovation-features)\n- [Tech Stack](#tech-stack)\n- [Architecture](#architecture)\n- [Quick Start (Docker)](#quick-start-docker)\n- [Local Development (without Docker)](#local-development-without-docker)\n- [Environment Variables](#environment-variables)\n- [API Documentation](#api-documentation)\n- [New API Endpoints](#new-api-endpoints)\n- [Deployment — Fly.io](#deployment--flyio)\n- [Deployment — Docker Compose Production](#deployment--docker-compose-production)\n- [User Roles](#user-roles)\n- [Project Structure](#project-structure)\n- [Makefile Commands](#makefile-commands)\n- [License](#license)\n\n---\n\n## Features\n\n### Core Platform\n\n| 🏷️ Area | ✨ Capabilities |\n|---------|----------------|\n| 🏢 **Multi-tenancy** | Each company is a fully isolated tenant — UUID PKs, cascading row-level scoping |\n| 👥 **Employees** | Full CRUD, department management, bulk Excel/CSV import, one-click export, risk scoring |\n| 🔒 **Documents** | Fernet AES-128 encryption at rest, OCR extraction, version control, expiry tracking \u0026 email alerts |\n| 🤖 **AI Extraction** | OCR auto-extracts employee name, salary, start/end dates from uploaded contracts |\n| ✅ **Compliance** | Tax, social security \u0026 labour law tracker; authority dashboards; full CRUD; bulk updates |\n| 🧠 **Health Pulse** | Rolling 6-month compliance trend + 30-day AI risk prediction |\n| 🔍 **Gap Analysis** | Auto-detects missing requirements vs your country + industry |\n| 📅 **Deadline Calendar** | Monthly calendar view of all compliance deadlines with iCal export |\n| 👤 **Self-Service Portal** | Employees see only their own payslips, documents, and compliance status |\n| 📊 **Reports** | Async PDF generation (WeasyPrint + Celery); scheduled delivery via email |\n| 💰 **Payroll** | Country-specific tax rule engine, payroll runs, payslip generation, variance alerts |\n| 🌍 **Geography** | 16+ countries, 17+ currencies, live exchange rate support |\n| 🔑 **Auth** | JWT rotate-on-refresh, Argon2 hashing, brute-force lockout (django-axes) |\n| 📜 **Audit Trail** | Immutable middleware log of every POST/PUT/PATCH/DELETE; CSV/PDF export |\n| 🔔 **Notifications** | In-app + email alerts, unread badge, mark-all-read |\n| 🏛️ **Portfolio** | Super-admin sees all tenant companies with live compliance scores |\n| 🔗 **Webhooks** | Outbound HMAC-signed webhooks for all platform events |\n| 🔗 **GraphQL** | Strawberry endpoint — Apollo-compatible at `/graphql/` |\n| 📖 **REST API** | Full DRF REST API with OpenAPI/Swagger docs at `/api/docs/` |\n\n### New Features (v2)\n\n| 🏷️ Area | ✨ Capabilities |\n|---------|----------------|\n| ✍️ **E-Signatures** | Request legally-binding document signatures from employees; track signing status per signer |\n| 🚀 **Onboarding** | Configurable onboarding checklists with task types (document, form, training, sign); progress tracking |\n| 🎓 **Training \u0026 Certifications** | Track employee certifications with validity periods, expiry alerts, and compliance reports |\n| 📋 **Policy Management** | Version-controlled policies with mandatory employee acknowledgment tracking and audit trail |\n| 🚨 **Incident Log** | Report and investigate compliance violations, data breaches, and safety incidents; update trail |\n| ✅ **Approval Workflows** | Configurable multi-step approval chains for documents, expenses, leave; full audit trail |\n| 🏭 **Vendor Compliance** | Vendor registry with compliance scores, insurance tracking, contract expiry monitoring |\n| 📝 **Custom Forms** | Drag-and-drop form builder; collect employee and vendor data with structured field types |\n| 🤝 **Partner / White-Label** | Partner portal with custom branding, sub-company management, revenue dashboards |\n| 🔌 **Integration Hub** | Connect QuickBooks, Xero, BambooHR, Slack, Google Workspace via OAuth; sync status \u0026 logs |\n| 📊 **Employee Risk Scores** | Composite risk scoring per employee based on document status, training gaps, compliance history |\n| 📅 **Scheduled Reports** | Schedule PDF reports for automatic email delivery (daily/weekly/monthly) |\n| 🔍 **Audit Prep Assistant** | Step-by-step audit readiness checklist with live progress score per regulatory framework |\n| 📱 **Mobile PWA** | Progressive Web App — installable on iOS/Android, offline capability, responsive design |\n\n---\n\n## Innovation Features\n\n### 🧠 Compliance Health Pulse\n`GET /api/v1/compliance/health-pulse/`\n\nReturns rolling 6-month history + linear regression prediction:\n```json\n{\n  \"current_score\": 78,\n  \"trend\": \"improving\",\n  \"predicted_30d\": 83,\n  \"risk_level\": \"moderate\",\n  \"days_to_threshold\": null,\n  \"history\": [\n    {\"month\": \"2025-10\", \"score\": 65},\n    {\"month\": \"2025-11\", \"score\": 70},\n    {\"month\": \"2025-12\", \"score\": 72},\n    {\"month\": \"2026-01\", \"score\": 74},\n    {\"month\": \"2026-02\", \"score\": 76},\n    {\"month\": \"2026-03\", \"score\": 78}\n  ]\n}\n```\n\n### 🔍 Compliance Gap Analysis\n`GET /api/v1/compliance/gap-analysis/`\n\nCompares your company's tracked requirements against the global requirement library for your country + industry. Returns prioritised list of missing requirements:\n```json\n{\n  \"total_gaps\": 4,\n  \"coverage_percent\": 76,\n  \"gaps\": [\n    {\n      \"requirement_id\": \"...\",\n      \"title\": \"Annual Tax Return Filing\",\n      \"authority\": \"IRS\",\n      \"priority\": \"high\",\n      \"is_mandatory\": true,\n      \"frequency\": \"annually\"\n    }\n  ]\n}\n```\n\n### ⚠️ Payroll Variance Check\n`POST /api/v1/payroll/runs/{id}/variance-check/`\n\nCompares current run against the previous completed run. Flags salary spikes \u003e15%, missing employees, and new additions.\n\n### 📤 Audit Trail Export\n`GET /api/v1/audit-logs/export/?format=csv\u0026date_from=2026-01-01\u0026date_to=2026-03-31`\n\nDownloads the audit trail as CSV (or JSON) for external auditors. Supports date range, method, and status filters.\n\n### 🏛️ Portfolio Dashboard\n`GET /api/v1/companies/portfolio/` _(super_admin only)_\n\nReturns all tenant companies with live compliance scores, employee counts, and last activity — for accounting firms managing multiple clients.\n\n### 🔗 Webhooks\n`/api/v1/webhooks/` — Full CRUD for webhook endpoints.\n\nConfigure outbound HTTP webhooks for platform events:\n- `employee.created` / `employee.updated`\n- `payroll.run.completed`\n- `document.expired` / `document.expiring_soon`\n- `compliance.overdue`\n\nAll deliveries are HMAC-SHA256 signed with `X-AuditShield-Signature` header. Automatic retry on failure.\n\n---\n\n## Tech Stack\n\n### 🐍 Backend\n\n| Technology | Version | Purpose |\n|-----------|:-------:|---------|\n| ![Python](https://img.shields.io/badge/-Python-3776AB?logo=python\u0026logoColor=white) **Python** | 3.12 | Runtime |\n| ![Django](https://img.shields.io/badge/-Django-092E20?logo=django\u0026logoColor=white) **Django** | 5.0 | Web framework |\n| ![DRF](https://img.shields.io/badge/-DRF-a30000?logo=django\u0026logoColor=white) **Django REST Framework** | 3.15 | REST API |\n| ![Strawberry](https://img.shields.io/badge/-Strawberry_GraphQL-E10098?logo=graphql\u0026logoColor=white) **Strawberry GraphQL** | 0.236 | GraphQL (Apollo-compatible) |\n| ![PostgreSQL](https://img.shields.io/badge/-PostgreSQL-4169E1?logo=postgresql\u0026logoColor=white) **PostgreSQL** | 16 | Primary database (Docker / self-hosted) |\n| ![SQLite](https://img.shields.io/badge/-SQLite-003B57?logo=sqlite\u0026logoColor=white) **SQLite** | 3 | Lightweight DB (Fly.io / CI) |\n| ![Redis](https://img.shields.io/badge/-Redis-DC382D?logo=redis\u0026logoColor=white) **Redis** | 7 | Celery message broker + cache |\n| ![Celery](https://img.shields.io/badge/-Celery-37814A?logo=celery\u0026logoColor=white) **Celery** + Beat | 5.3 | Async task queue + scheduler |\n| **Gunicorn** gthread | — | Production WSGI server |\n| **drf-spectacular** | 0.27 | Auto OpenAPI / Swagger docs |\n| **WeasyPrint** | 61 | PDF report generation |\n| **pytesseract** | 0.3 | OCR text extraction from documents |\n| **cryptography** (Fernet) | 42 | AES-128 file encryption at rest |\n| **django-axes** | 6.4 | Brute-force login protection |\n| **Argon2** | — | Strongest password hashing |\n\n### 🅰️ Frontend\n\n| Technology | Version | Purpose |\n|-----------|:-------:|---------|\n| ![Angular](https://img.shields.io/badge/-Angular-DD0031?logo=angular\u0026logoColor=white) **Angular** | 18 | SPA framework — standalone components + signals |\n| ![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript\u0026logoColor=white) **TypeScript** | 5 | Strict type-safe development |\n| ![Material](https://img.shields.io/badge/-Angular_Material-757575?logo=materialdesign\u0026logoColor=white) **Angular Material** | 18 | UI component library |\n| ![Apollo](https://img.shields.io/badge/-Apollo_Angular-311C87?logo=apollographql\u0026logoColor=white) **Apollo Angular** | 7 | GraphQL client |\n| **RxJS** | 7 | Reactive streams \u0026 observables |\n\n### 🏗️ Infrastructure\n\n| Technology | Purpose |\n|-----------|---------|\n| ![Docker](https://img.shields.io/badge/-Docker-2496ED?logo=docker\u0026logoColor=white) **Docker Compose** | Dev (7 services) + Production stacks |\n| ![Nginx](https://img.shields.io/badge/-Nginx-009639?logo=nginx\u0026logoColor=white) **Nginx** | Reverse proxy, SSL termination, static serving |\n| ![Fly.io](https://img.shields.io/badge/-Fly.io-8b5cf6?logo=flydotio\u0026logoColor=white) **Fly.io** | Backend cloud deployment with persistent volume |\n| ![GitHub Actions](https://img.shields.io/badge/-GitHub_Actions-2088FF?logo=githubactions\u0026logoColor=white) **GitHub Actions** | CI/CD — lint, test, coverage, auto-deploy |\n\n---\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────────────────────┐\n│                        User's Browser                           │\n│               Angular 18 SPA  (TypeScript + Signals)           │\n└────────────────────────────┬────────────────────────────────────┘\n                             │  HTTPS\n                ┌────────────▼────────────┐\n                │      Nginx :80/:443     │\n                │  /api/v1/* → Django     │\n                │  /graphql/ → Django     │\n                │  /*        → Angular    │\n                └────────────┬────────────┘\n                             │\n          ┌──────────────────▼────────────────────────┐\n          │    Django 5  +  DRF  +  Strawberry GQL   │\n          │  ┌────────────────────────────────────┐   │\n          │  │  JWT Auth │  Tenant  │  AuditLog  │   │\n          │  │ middleware│  scoping │  middleware │   │\n          │  └────────────────────────────────────┘   │\n          │          REST API ──── GraphQL API         │\n          └──────────┬───────────────────────────────┘\n                     │\n        ┌────────────┴─────────────┐\n        │                          │\n┌───────▼────────┐       ┌─────────▼───────┐\n│  PostgreSQL 16 │       │    Redis 7       │\n│  (app data)    │       │  broker + cache  │\n└────────────────┘       └─────────┬───────┘\n                                   │\n                    ┌──────────────▼─────────────┐\n                    │     Celery Workers + Beat   │\n                    │  📄 OCR · 📊 PDF reports    │\n                    │  📧 Emails · 💾 Backups     │\n                    │  🔔 Reminders · 🧹 Cleanup  │\n                    └────────────────────────────┘\n```\n\n---\n\n## Quick Start (Docker)\n\n\u003e **Prerequisites**: Docker Desktop ≥ 24 with the Compose v2 plugin\n\n```bash\n# 1. Clone\ngit clone https://github.com/manziosee/auditshield.git\ncd auditshield\n\n# 2. Environment file\ncp .env.example .env\n\n# 3. Generate required secret keys\nmake gen-secret    # → paste as DJANGO_SECRET_KEY in .env\nmake gen-fernet    # → paste as FILE_ENCRYPTION_KEY in .env\n\n# Also set DATABASE_URL in .env:\n# DATABASE_URL=postgresql://auditshield:auditshield@db:5432/auditshield\n\n# 4. Start the full stack (PostgreSQL + Redis + Django + Celery + Angular + Nginx)\nmake dev\n\n# 5. Create your admin user\nmake createsuperuser\n\n# 6. (Optional) Seed realistic demo data across all 18 modules\ndocker compose exec backend python manage.py seed_demo_data\n# Login: admin@technova.com / Demo@12345\n\n# 7. Open the app 🎉\n```\n\n| Service | URL |\n|---------|-----|\n| 🌐 **Frontend** | http://localhost:4200 |\n| 🔌 **API** | http://localhost:8000/api/v1/ |\n| 📖 **Swagger UI** | http://localhost:8000/api/docs/ |\n| 🔗 **GraphiQL** | http://localhost:8000/graphql/ |\n| 🌸 **Flower (Celery)** | http://localhost:5555 |\n\n### Demo Credentials\n\nAfter running `seed_demo_data`:\n\n| Role | Email | Password |\n|------|-------|----------|\n| Admin | admin@technova.com | Demo@12345 |\n| HR | hr@technova.com | Demo@12345 |\n| Accountant | accountant@technova.com | Demo@12345 |\n| Auditor | auditor@technova.com | Demo@12345 |\n| Employee | emp1@technova.com | Demo@12345 |\n\n---\n\n## Local Development (without Docker)\n\n### Backend\n\n```bash\ncd backend\npython3 -m venv .venv \u0026\u0026 source .venv/bin/activate\npip install -r requirements/development.txt\n\n# In .env: set TURSO_DATABASE_URL=file:db.sqlite3  (remove DATABASE_URL line)\npython manage.py migrate\npython manage.py seed_global_data   # loads countries, currencies, authorities\npython manage.py createsuperuser\npython manage.py runserver          # → http://localhost:8000\n```\n\n### Frontend\n\n```bash\ncd frontend\nnpm install\nnpm start   # → http://localhost:4200\n```\n\n### Celery (optional — needed for PDF gen, OCR, email)\n\n```bash\ncd backend\ncelery -A auditshield worker --loglevel=info -Q default,documents,reports,notifications\ncelery -A auditshield beat   --loglevel=info --scheduler django_celery_beat.schedulers:DatabaseScheduler\n```\n\n---\n\n## Environment Variables\n\n| Variable | Required | Description |\n|----------|:--------:|-------------|\n| `DJANGO_SECRET_KEY` | ✅ | Django secret key (50+ chars) |\n| `FILE_ENCRYPTION_KEY` | ✅ | Fernet key — document encryption at rest |\n| `DATABASE_URL` | 🐳 Docker | PostgreSQL `postgresql://user:pass@host/db` |\n| `TURSO_DATABASE_URL` | ✈️ Fly.io/CI | SQLite `file:db.sqlite3` |\n| `REDIS_URL` | ✅ | `redis://:password@host:6379/0` |\n| `CELERY_BROKER_URL` | ✅ | Celery broker (Redis) |\n| `DJANGO_ALLOWED_HOSTS` | 🚀 Prod | Comma-separated hostnames |\n| `CORS_ALLOWED_ORIGINS` | 🚀 Prod | Comma-separated frontend origins |\n| `EMAIL_HOST_USER` | optional | SMTP username |\n| `EMAIL_HOST_PASSWORD` | optional | SMTP app password |\n| `SENTRY_DSN` | optional | Sentry error tracking |\n| `DB_NAME / DB_USER / DB_PASSWORD` | 🐳 Docker | PostgreSQL credentials |\n\n---\n\n## API Documentation\n\n\u003e All endpoints require `Authorization: Bearer \u003caccess_token\u003e` except `/health/`, `/auth/register/`, `/auth/login/`.\n\n### Login\n\n```http\nPOST /api/v1/auth/login/\nContent-Type: application/json\n\n{ \"email\": \"admin@company.com\", \"password\": \"yourpassword\" }\n```\n\n### Key Endpoints\n\n| Method | Endpoint | Description |\n|--------|----------|-------------|\n| `GET` | `/health/` | Health check — no auth |\n| `POST` | `/api/v1/auth/register/` | Register company + admin |\n| `POST` | `/api/v1/auth/login/` | Obtain JWT tokens |\n| `GET/PATCH` | `/api/v1/companies/me/` | Company profile |\n| `GET` | `/api/v1/companies/export/` | Export all company data |\n| `GET/POST` | `/api/v1/employees/` | List / create employees |\n| `GET/PATCH/DELETE` | `/api/v1/employees/{id}/` | Employee detail |\n| `POST` | `/api/v1/employees/bulk-import/` | Import from Excel/CSV |\n| `GET/POST` | `/api/v1/employees/departments/` | List / create departments |\n| `GET/POST` | `/api/v1/documents/` | List / upload documents |\n| `GET` | `/api/v1/documents/{id}/download/` | Download decrypted file |\n| `DELETE` | `/api/v1/documents/{id}/` | Delete document |\n| `GET` | `/api/v1/compliance/dashboard/` | Compliance score + stats |\n| `GET/POST` | `/api/v1/compliance/records/` | List / create records |\n| `PATCH/DELETE` | `/api/v1/compliance/records/{id}/` | Update / delete record |\n| `GET` | `/api/v1/reports/` | List reports |\n| `POST` | `/api/v1/reports/` | Generate report (async) |\n| `POST` | `/api/v1/notifications/mark-all-read/` | Mark all read |\n| `GET` | `/api/v1/notifications/unread-count/` | Unread count |\n| `GET` | `/api/v1/audit-logs/` | Audit trail |\n| `GET` | `/api/v1/geo/countries/` | Countries list |\n| `GET` | `/api/v1/geo/currencies/` | Currencies list |\n\n\u003e 📦 **Postman collection** → [`postman_collection.json`](postman_collection.json)\n\u003e\n\u003e 📖 **Swagger** → `/api/docs/` · **ReDoc** → `/api/redoc/` · **GraphiQL** → `/graphql/`\n\n---\n\n## Deployment — Fly.io\n\n```bash\n# Install CLI\ncurl -L https://fly.io/install.sh | sh \u0026\u0026 flyctl auth login\n\n# Create persistent SQLite volume\nflyctl volumes create auditshield_data --region jnb --size 3 --config backend/fly.toml\n\n# Set secrets\nflyctl secrets set \\\n  DJANGO_SECRET_KEY=\"\u003cgenerated\u003e\" \\\n  FILE_ENCRYPTION_KEY=\"\u003cgenerated\u003e\" \\\n  DJANGO_ALLOWED_HOSTS=\"auditshield-backend.fly.dev\" \\\n  CORS_ALLOWED_ORIGINS=\"https://your-frontend.fly.dev\" \\\n  --config backend/fly.toml\n\n# Deploy\nflyctl deploy --config backend/fly.toml\n```\n\n**Auto-deploy on push to `main`**: Add `FLY_API_TOKEN` to GitHub repo secrets → (**Settings → Secrets → Actions**).\n\n### Live Production URLs\n\n| | URL |\n|---|---|\n| 🌐 **API Base** | https://auditshield-backend.fly.dev/api/v1/ |\n| 📖 **Swagger UI** | https://auditshield-backend.fly.dev/api/docs/ |\n| 📄 **ReDoc** | https://auditshield-backend.fly.dev/api/redoc/ |\n| 🔗 **GraphiQL** | https://auditshield-backend.fly.dev/graphql/ |\n| ❤️ **Health check** | https://auditshield-backend.fly.dev/health/ |\n\n---\n\n## Deployment — Docker Compose Production\n\n```bash\ngit clone https://github.com/manziosee/auditshield.git \u0026\u0026 cd auditshield\ncp .env.example .env  # fill in production values\n\ndocker compose -f docker-compose.yml -f docker-compose.prod.yml up -d\ndocker compose exec backend python manage.py createsuperuser\n```\n\nPlace SSL certs in `nginx/ssl/` and configure your domain in `nginx/nginx.prod.conf`.\n\n---\n\n## User Roles\n\n| Role | Access |\n|------|--------|\n| 👑 `super_admin` | Full platform access |\n| 🔧 `admin` | Company admin — full access to own tenant |\n| 👩‍💼 `hr` | Employees, documents, compliance |\n| 🧾 `accountant` | Payroll, financial reports |\n| 🔍 `auditor` | Read-only + audit logs |\n| 👤 `employee` | Own profile and documents only |\n\n---\n\n## Project Structure\n\n```\nauditshield/\n├── 🐍 backend/\n│   ├── auditshield/settings/       # base / development / production\n│   ├── apps/\n│   │   ├── accounts/               # User + JWT auth\n│   │   ├── companies/              # Company (tenant) + onboarding\n│   │   ├── employees/              # Employee + Department\n│   │   ├── documents/              # Encrypted upload + OCR\n│   │   ├── compliance/             # Authority + Requirements + Records\n│   │   ├── reports/                # PDF generation (WeasyPrint)\n│   │   ├── notifications/          # In-app + email alerts\n│   │   ├── audit_logs/             # Immutable activity trail\n│   │   ├── geography/              # Country + Currency + ExchangeRate\n│   │   └── payroll/                # TaxRule + PayrollRun + Payslip\n│   ├── core/                       # Shared: TenantModel, middleware, utils\n│   ├── Dockerfile.dev / Dockerfile.prod\n│   ├── entrypoint.sh               # Fly.io startup script\n│   └── fly.toml                    # Fly.io deployment config\n│\n├── 🅰️ frontend/src/app/\n│   ├── core/                       # Guards, interceptors, services, models\n│   ├── features/\n│   │   ├── auth/                   # Login + Register pages\n│   │   ├── dashboard/              # KPI cards + live charts\n│   │   ├── employees/              # List, Detail, Form (CRUD)\n│   │   ├── documents/              # List, Upload, Detail (CRUD)\n│   │   ├── compliance/             # Tracker + Add/Edit/Delete\n│   │   ├── reports/                # List + Generate\n│   │   ├── notifications/          # Notification centre\n│   │   ├── audit-logs/             # Audit log viewer\n│   │   └── company/                # Company settings\n│   └── shared/layout/              # Shell — sidebar + topbar\n│\n├── 🌐 nginx/                       # nginx.dev.conf / nginx.prod.conf\n├── 💾 scripts/backup/              # GPG-encrypted backup + restore\n├── ⚙️  .github/workflows/          # CI/CD pipelines\n├── 🐳 docker-compose.yml           # Dev stack\n├── 🐳 docker-compose.prod.yml      # Production overrides\n├── 📦 postman_collection.json      # Full Postman API collection\n├── 🔧 Makefile\n└── 📋 .env.example\n```\n\n---\n\n## Makefile Commands\n\n```bash\nmake dev              # Start dev stack (docker compose up --build)\nmake stop             # Stop all services\nmake logs             # Tail all service logs\nmake migrate          # Run database migrations\nmake makemigrations   # Create new migrations\nmake shell            # Django shell_plus\nmake createsuperuser  # Create admin user\nmake seed             # Seed global countries, currencies, authorities\nmake test             # Run Django test suite\nmake lint             # Ruff linter\nmake coverage         # Tests with coverage report\nmake deploy           # Deploy backend to Fly.io\nmake build-prod       # Build production Docker images\nmake backup           # GPG-encrypted DB + media backup\nmake gen-secret       # Generate DJANGO_SECRET_KEY\nmake gen-fernet       # Generate FILE_ENCRYPTION_KEY\n```\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**MIT License** — Copyright © 2026 [Osee Manzi](mailto:oseemanzi3@gmail.com)\n\n_Built with ❤️ to make compliance accessible for every SME, everywhere._\n\n\u003c/div\u003e\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanziosee%2Fauditshield","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmanziosee%2Fauditshield","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmanziosee%2Fauditshield/lists"}