{"id":51482444,"url":"https://github.com/carturo8/text-to-pdf-service","last_synced_at":"2026-07-07T03:00:50.309Z","repository":{"id":333269601,"uuid":"1136706948","full_name":"Carturo8/text-to-pdf-service","owner":"Carturo8","description":"🚀 Professional Text-to-PDF service built with Hexagonal Architecture. Features FastAPI, Typer CLI, Docker support, and bilingual documentation (EN/ES). Optimized for privacy and observability.","archived":false,"fork":false,"pushed_at":"2026-01-18T10:29:59.000Z","size":154,"stargazers_count":0,"open_issues_count":10,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-18T17:37:14.237Z","etag":null,"topics":["api-rest","clean-architecture","docker","fastapi","hexagonal-architecture","markdown-to-pdf","pdf-generation","professional-tools","python","typer-cli"],"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/Carturo8.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","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-01-18T07:31:36.000Z","updated_at":"2026-01-18T10:11:15.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Carturo8/text-to-pdf-service","commit_stats":null,"previous_names":["carturo8/text-to-pdf-service"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Carturo8/text-to-pdf-service","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Carturo8%2Ftext-to-pdf-service","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Carturo8%2Ftext-to-pdf-service/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Carturo8%2Ftext-to-pdf-service/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Carturo8%2Ftext-to-pdf-service/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Carturo8","download_url":"https://codeload.github.com/Carturo8/text-to-pdf-service/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Carturo8%2Ftext-to-pdf-service/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35212581,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-07T02:00:07.222Z","response_time":90,"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":["api-rest","clean-architecture","docker","fastapi","hexagonal-architecture","markdown-to-pdf","pdf-generation","professional-tools","python","typer-cli"],"created_at":"2026-07-07T03:00:45.593Z","updated_at":"2026-07-07T03:00:50.287Z","avatar_url":"https://github.com/Carturo8.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Text to PDF Service\n\n\u003e **Note:** This project is an AI-assisted software engineering experiment led by **Carlos Arturo Rojas Bolaños**, exploring autonomous development capabilities while maintaining strict quality patterns and hexagonal architecture.\n\nA professional service to convert Markdown and Text documents to styled PDF files.\n\n## License\n\nDistributed under the MIT License. Copyright (c) 2026 Carlos Arturo Rojas Bolaños. See [LICENSE](LICENSE) for details.\n\n## Features\n\n*   **Clean Architecture**: Strictly follows Hexagonal Architecture (Ports \u0026 Adapters) pattern\n*   **Multiple Interfaces**: REST API (FastAPI) and CLI (Typer)\n*   **Format Support**: Markdown (with tables, code blocks) and Plain Text\n*   **Professional Styling**: Clean, readable PDF output with proper typography\n*   **Multi-file Upload**: Upload multiple files and get a ZIP with all PDFs\n*   **Bulk Processing**: Process local files via API endpoint\n*   **Docker Ready**: Fully containerized with Docker Compose\n*   **Comprehensive Logging**: Color-coded console + file rotation in `logs/service.log`\n*   **Observability**: Integrated request tracing (`X-Request-ID`) and performance monitoring (`X-Process-Time`)\n*   **Auto-generated Documentation**: Interactive Swagger UI at `/docs`\n\n## Branching Strategy\n\nThis project follows a professional branching model for continuous evolution:\n\n*   **`main`**: Production-ready code. Only contains stable, tagged releases (v1.x.x).\n*   **`develop`**: Integration branch for the next release. **IMPORTANT: All Pull Requests from the community must target this branch.**\n*   **`workspace/v1-next`**: **Reserved for project owner.** Active development branch for upcoming version prototyping and internal evolution.\n\n## Project Structure\n\n```\ntext-to-pdf-service/\n├── src/\n│   ├── domain/           # Core business logic (models, ports, exceptions)\n│   ├── application/      # Use cases (Conversion Service)\n│   ├── adapters/\n│   │   ├── driving/      # API and CLI\n│   │   └── driven/       # PDF and FileSystem implementations\n│   └── infrastructure/   # Cross-cutting concerns (logger)\n├── tests/                # Unit and integration tests\n│   ├── unit/\n│   └── integration/\n├── scripts/              # Development scripts\n├── data/                 # Working directories\n│   ├── input/            # Place source files for bulk processing\n│   └── output/           # Generated PDFs appear here\n├── logs/                 # Application logs\n└── docs/                 # Documentation (with docs/es/ for Spanish)\n```\n\n## Quick Start\n\n### Using Docker (Recommended)\n\n```bash\ndocker-compose up --build\n```\n\nThe API will be available at `http://localhost:8000`.\n\n### Starting from Zero (Docker)\n\nIf you want to perform a clean-wipe and start fresh:\n\n```bash\n# 1. Stop and remove everything related to the project\ndocker-compose down --rmi all --volumes --remove-orphans\n\n# 2. Build and start from scratch\ndocker-compose up -d --build\n```\n\n**Docker Management Commands:**\n```bash\n# Run in background\ndocker-compose up -d\n\n# View logs\ndocker-compose logs -f\n\n# Stop and remove containers\ndocker-compose down\n```\n\n### Local Development\n\n**Prerequisites**: Python 3.11.9 (Recommended), Poetry\n\n```bash\n# Install dependencies\npoetry install\n\n# Run API server\npoetry run uvicorn src.adapters.driving.api:app --reload\n\n# Or use CLI\npoetry run python -m src.adapters.driving.cli convert input.md output.pdf\n```\n\n## Usage\n\n### REST API\n\n**Interactive Documentation**: Open `http://localhost:8000/docs` in your browser.\n\n#### Convert Single File\n```bash\ncurl -X POST \"http://localhost:8000/convert/\" \\\n  -F \"file=@document.md\" \\\n  --output result.pdf\n```\n\n#### Convert Multiple Files (NEW!)\nUpload multiple files and receive a ZIP with all PDFs:\n```bash\ncurl -X POST \"http://localhost:8000/convert/multiple\" \\\n  -F \"files=@doc1.md\" \\\n  -F \"files=@doc2.md\" \\\n  -F \"files=@doc3.txt\" \\\n  --output results.zip\n```\n**Limits**: Max 20 files, 10MB/file, 50MB total.\n\n#### Bulk Convert Local Files\nProcess all files in `data/input/`:\n```bash\ncurl -X POST \"http://localhost:8000/bulk-convert\"\n```\nCheck `data/output/` for generated PDFs.\n\n### Command Line\n\n```bash\npoetry run python -m src.adapters.driving.cli convert input.md output.pdf\n```\n\n### Local Batch Script\n\n```bash\n# Process all files from data/input to data/output\npoetry run python scripts/process_local.py\n```\n\n### Automation Workflows\n\nThis project includes standardized workflows in `.agent/workflows/` to simplify common tasks:\n\n- **Setup**: `setup.md` - Complete environment initialization.\n- **Serve**: `serve.md` - Start the API server with correct paths.\n\nIf using an Agentic IDE (like Antigravity), you can run these directly via slash commands (e.g., `/setup`, `/serve`).\n\n## Documentation\n\n### 📖 Table of Contents\n\n| Topic | English | Español |\n|-------|---------|---------|\n| **Architecture** | [architecture.md](docs/architecture.md) | [architecture.md](docs/es/architecture.md) |\n| **API Reference** | [api.md](docs/api.md) | [api.md](docs/es/api.md) |\n| **Testing** | [tests.md](docs/tests.md) | [tests.md](docs/es/tests.md) |\n| **Contributing** | [CONTRIBUTING.md](CONTRIBUTING.md) | [CONTRIBUTING.md](docs/es/CONTRIBUTING.md) |\n| **Code of Conduct** | [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) | [CODE_OF_CONDUCT.md](docs/es/CODE_OF_CONDUCT.md) |\n| **Commit Conventions** | [COMMIT_CONVENTIONS.md](docs/COMMIT_CONVENTIONS.md) | [COMMIT_CONVENTIONS.md](docs/es/COMMIT_CONVENTIONS.md) |\n| **AI Development** | [AI_DEVELOPMENT.md](docs/AI_DEVELOPMENT.md) | [AI_DEVELOPMENT.md](docs/es/AI_DEVELOPMENT.md) |\n\n## Testing\n\n```bash\n# Run all tests with coverage\npoetry run pytest --cov=src --cov-report=term-missing\n\n# Run specific test file\npoetry run pytest tests/unit/test_service.py -v\n```\n\n**Current Coverage**: 62%  \n**Target Coverage**: 70%+\n\n## Observability \u0026 Monitoring\n\nThe service includes professional observability features out-of-the-box:\n\n- **Request Tracing**: Every API request is assigned a unique `X-Request-ID`. This ID is returned in the response headers and included in all logs related to that request, enabling precise end-to-end tracing.\n- **Performance Headers**: The `X-Process-Time` response header reports the exact time (in seconds) the server took to process the conversion.\n- **Structured Logs**: Application logs are stored in `logs/service.log` with a rotating strategy. Console output is color-coded for fast visual debugging.\n\nLog colors:\n- 🟢 INFO (Green)\n- 🟡 WARNING (Yellow)\n- 🔴 ERROR (Red)\n- 🟣 CRITICAL (Magenta)\n\n## Development\n\n### Code Style\n*   All code, comments, and docstrings: **English**\n*   User-facing output/reports: **Spanish**\n*   Follow PEP 8 and Hexagonal Architecture principles\n\n### Commit Conventions\nThis project uses **Conventional Commits** with required scopes. See [COMMIT_CONVENTIONS.md](docs/COMMIT_CONVENTIONS.md).\n\n### Adding Features\n1. Define domain model in `src/domain/`\n2. Create port (interface) if needed\n3. Implement adapter in `src/adapters/driven/`\n4. Update service in `src/application/`\n5. Expose via API or CLI in `src/adapters/driving/`\n6. Write tests\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.\n\nQuick checklist:\n*   Tests pass (`poetry run pytest`)\n*   Code follows project architecture\n*   Commit messages follow conventions\n*   Public documentation has Spanish version\n\n## Roadmap\n\n*   ✅ V1.0: Core conversion, API, CLI, Docker\n*   ✅ V1.0: Multi-file upload endpoint\n*   ✅ V1.0: Advanced observability and tracing\n*   ✅ V1.0: Professional documentation (EN/ES)\n\n## Cross-Platform Guide\n\nThe service is designed to run seamlessly on Windows, Linux, and macOS.\n\n| Feature | Windows (PowerShell/CMD) | Linux / macOS (Bash/Zsh) |\n|---------|-------------------------|--------------------------|\n| **Paths** | `data\\input`, `.\\.venv` | `data/input`, `./.venv` |\n| **Env Activation** | `.venv\\Scripts\\Activate.ps1` | `source .venv/bin/activate` |\n| **Python Command** | `python` or `py` | `python3` |\n| **Docker** | Docker Desktop (Hyper-V/WSL2) | Docker Engine (Native) |\n\n\u003e [!TIP]\n\u003e **Why Docker?** Using Docker is the **highly recommended** way to run the service in non-Windows environments or production, as it eliminates \"it works on my machine\" issues by packaging all OS dependencies (like PDF libraries) into a consistent container.\n\n---\n\n**Maintainer**: Carlos Arturo Rojas Bolaños  \n**Repository**: text-to-pdf-service  \n**Version**: 1.0.0\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarturo8%2Ftext-to-pdf-service","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarturo8%2Ftext-to-pdf-service","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarturo8%2Ftext-to-pdf-service/lists"}