{"id":31749124,"url":"https://github.com/pvotio/nava2","last_synced_at":"2026-05-05T19:32:52.021Z","repository":{"id":315763529,"uuid":"1052875123","full_name":"pvotio/nava2","owner":"pvotio","description":"Nava2 is an open-source service for generating customizable, data-driven reports and PDFs.","archived":false,"fork":false,"pushed_at":"2025-10-27T10:34:55.000Z","size":114,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-27T12:26:42.438Z","etag":null,"topics":["async","celery","fastapi","jinja2","puppeteer","python","redis","reports"],"latest_commit_sha":null,"homepage":"","language":"Python","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/pvotio.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":"2025-09-08T17:07:47.000Z","updated_at":"2025-10-27T10:34:59.000Z","dependencies_parsed_at":"2025-09-20T16:25:56.696Z","dependency_job_id":"e2bcc554-88dc-4c4e-a512-5e7102b1ebc3","html_url":"https://github.com/pvotio/nava2","commit_stats":null,"previous_names":["pvotio/nava2"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/pvotio/nava2","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvotio%2Fnava2","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvotio%2Fnava2/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvotio%2Fnava2/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvotio%2Fnava2/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pvotio","download_url":"https://codeload.github.com/pvotio/nava2/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pvotio%2Fnava2/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32664945,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-05T11:29:49.557Z","status":"ssl_error","status_checked_at":"2026-05-05T11:29:48.587Z","response_time":54,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["async","celery","fastapi","jinja2","puppeteer","python","redis","reports"],"created_at":"2025-10-09T14:31:30.896Z","updated_at":"2026-05-05T19:32:52.009Z","avatar_url":"https://github.com/pvotio.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nava2 - Asynchronous Reporting Platform\n\nNava2 is a **modern, asynchronous reporting platform** built with [FastAPI](https://fastapi.tiangolo.com/), [Celery](https://docs.celeryq.dev/), and [PostgreSQL](https://www.postgresql.org/).  \nIt enables dynamic report generation based on **external data sources** (such as MSSQL) and customizable **Python-driven templates**, producing downloadable **PDF reports** through a headless [Puppeteer](https://pptr.dev/) service.\n\n---\n\n## Overview\n\n### Key Features\n- **Async report generation** with Celery and Redis  \n- **Templated reports** defined in a remote GitHub repository  \n- **Dynamic Python logic** and validation for each report  \n- **Multi-database support** (MSSQL, PostgreSQL, MySQL, MariaDB - extensible)  \n- **Automated PDF rendering** using a Node.js Puppeteer microservice  \n- **Admin endpoints** for monitoring, syncing, and auditing reports  \n- **Secure authentication** via JWT with role-based access (User, Admin)\n\n---\n\n## Environment Configuration\n\n### Example `.env`\n\n```bash\n# Core\nSECRET_KEY=change-me\nBASE_URL=http://localhost:8000\nACCESS_TOKEN_EXPIRE_MINUTES=60\n\n# Storage\nMEDIA_DIR=/data/media\nMEDIA_URL=/files\n\n# Databases\nDATABASE_URL=postgresql+psycopg2://postgres:postgres@postgres:5432/nava2\nCELERY_BROKER_URL=redis://redis:6379/0\nCELERY_RESULT_BACKEND=redis://redis:6379/1\n\n# MSSQL connection (for report data)\nMSSQL_DSN=Driver={ODBC Driver 18 for SQL Server};Server=your-server,1433;Database=yourdb;UID=user;PWD=pass;Encrypt=yes;TrustServerCertificate=yes;\n```\n\nAlso copy `db.env.example` → `db.env` for PostgreSQL container credentials.\n\n---\n\n## Quick Start (Docker Compose)\n\nNava2 ships with a ready-to-run **Docker Compose** setup for local development.\n\n```bash\n# Build and start all services\ndocker compose up --build\n```\n\n### Services\n\n| Service | Description | Port |\n|----------|--------------|------|\n| **web** | FastAPI application (REST API + docs) | 8000 |\n| **worker** | Celery worker processing report tasks | — |\n| **beat** | Celery beat scheduler (periodic jobs) | — |\n| **generator** | Puppeteer PDF renderer | 3000 (internal) |\n| **postgres** | PostgreSQL database | 5432 |\n| **redis** | Redis (broker \u0026 cache) | 6379 |\n\n---\n\n## Concepts\n\n### 1. Templates Repository\nEach report template lives in a GitHub repo and defines:\n- **`map.json`** - registry of available templates, arguments, and metadata\n- **`logic.py`** - main script generating placeholders for rendering\n- **`test.py`** - optional pre-check or data validation logic\n- **`template.html`** - Jinja2-compatible HTML file for rendering\n\nTemplates are fetched and cached in Redis. The system periodically syncs the index via Celery beat.\n\n---\n\n### 2. Report Lifecycle\n\n| Stage | Description |\n|--------|-------------|\n| **Pending (P)** | Report request created |\n| **Fetched (F)** | Template and arguments validated |\n| **Generated (G)** | PDF successfully rendered |\n| **Failed (F)** | Exception occurred during processing |\n| **Deleted (D)** | Cleaned up or expired |\n\n---\n\n## Authentication\n\nJWT-based authentication.\n\n- `POST /api/auth/login` → get token  \n- Use the token in `Authorization: Bearer \u003ctoken\u003e` header for all protected endpoints  \n- Admin endpoints require `is_admin=True` flag on the user\n\nPublic endpoints (e.g., `GET /api/reports/{hash_id}`) allow unauthenticated access to finalized reports.\n\n---\n\n## Endpoints (Highlights)\n\n| Method | Endpoint | Description | Auth |\n|--------|-----------|-------------|------|\n| **POST** | `/api/reports` | Submit new report request | ✅ Required |\n| **GET** | `/api/reports/{hash_id}` | Publicly retrieve report and PDF link | ❌ Optional |\n| **POST** | `/api/admin/templates/sync` | Force sync templates index and assets | ✅ Admin |\n| **GET** | `/api/admin/reports` | List and audit reports | ✅ Admin |\n\nExplore the full OpenAPI documentation at:  \n**[http://localhost:8000/docs](http://localhost:8000/docs)**\n\n---\n\n## Media Files\n\nGenerated PDFs are stored inside a shared Docker volume (`media`) and served directly by the FastAPI application.\n\n- Directory inside containers: `/files`\n- URL prefix: `/files`\n- Example URL:  \n  ```\n  http://localhost:8000/files/report_hello_simple_1234abcd.pdf\n  ```\n\n---\n\n## Development \u0026 Tooling\n\n### Run migrations\n```bash\ndocker compose exec web alembic upgrade head\n```\n\n### Create or update a user\n```bash\ndocker compose exec web python -m app.cli create-user -e user@example.com -p secret\n```\n\n### Logs (for debugging)\n```bash\ndocker compose logs -f web\ndocker compose logs -f worker\n```\n\n### Static checks\n```bash\nruff check . --fix\n```\n\n---\n\n## Contributing\n\nWe welcome contributions!  \nPlease ensure PRs follow the existing code style and include tests when applicable.\n\n1. Fork this repository  \n2. Create a new branch (`feature/my-feature`)  \n3. Submit a pull request once tested\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpvotio%2Fnava2","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpvotio%2Fnava2","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpvotio%2Fnava2/lists"}