{"id":26934365,"url":"https://github.com/mdevpro78/roman_numeral_converter","last_synced_at":"2025-04-02T10:36:50.227Z","repository":{"id":258001995,"uuid":"872631537","full_name":"Mdevpro78/roman_numeral_converter","owner":"Mdevpro78","description":"a fastapi project to convert roman numerals to integer","archived":false,"fork":false,"pushed_at":"2025-01-24T21:03:17.000Z","size":93,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-01-24T21:26:42.404Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://roman-numeral-converter-omega.vercel.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Mdevpro78.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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}},"created_at":"2024-10-14T19:26:32.000Z","updated_at":"2025-01-24T21:03:21.000Z","dependencies_parsed_at":"2024-10-17T08:42:30.831Z","dependency_job_id":null,"html_url":"https://github.com/Mdevpro78/roman_numeral_converter","commit_stats":null,"previous_names":["mdevpro78/roman_numeral_converter"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mdevpro78%2Froman_numeral_converter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mdevpro78%2Froman_numeral_converter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mdevpro78%2Froman_numeral_converter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Mdevpro78%2Froman_numeral_converter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Mdevpro78","download_url":"https://codeload.github.com/Mdevpro78/roman_numeral_converter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246800080,"owners_count":20836103,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":[],"created_at":"2025-04-02T10:36:49.688Z","updated_at":"2025-04-02T10:36:50.190Z","avatar_url":"https://github.com/Mdevpro78.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Roman Numerals To Integer Convertor (FastAPI Version)\n\n## Table of Contents\n\n- [About](#about)\n- [Getting Started](#getting_started)\n- [Usage](#usage)\n- [Algorithm Explaination](#algorithm)\n- [Tasks](#tasks)\n- [Git Convention](#git)\n\n## About\n\nThis Project is a web API to convert the roman numerals to integer number through REST API implemented by **FastAPI**\n\n## Getting Started\n\nThese instructions will help you run the project on your local machine using Docker Compose.\n\n### Prerequisites\n\n1. Docker and Docker Compose\n\n### Installing\n\nuse the following docker compose command to mange the app.\n\n#### Environment Setup\n\nTo run the app:\n\n- Description: Starts the application using Docker Compose.\n- Command: `docker compose -f docker-compose.yaml up -d`\n\n#### Build Commands\n\nTo build the docker image of app:\n\n- Description: Builds the Docker images without using cache.\n- Command: `docker compose -f docker-compose.yaml build --no-cache`\n\nTo remove the built image of app :\n\n- Description: Removes the latest Docker image for the Roman Converter.\n- Command: `docker image rm roman-conveter:latest`\n\n#### Docker Management\n\nTo stop app:\n\n- Description: Stops and removes containers, networks, volumes, and images created by `up`.\n- Command: `docker compose -f docker-compose.yaml down -v`\n\nTo show the app container log:\n\n- Description: Follows the logs of the running containers.\n- Command: `docker compose -f docker-compose.yaml logs -f`\n\nTo show status of app contianer:\n\n- Description: Lists all containers, including stopped ones.\n- Command: `docker compose -f docker-compose.yaml ps -a`\n\n## Usage `\u003ca name = \"usage\"\u003e\u003c/a\u003e`\n\n### App Execution Flow\n\n1. create .env file\n\n```bash\ncp env-example .env\n```\n\n2. build app image:\n\n```bash\ndocker compose -f docker-compose.yaml build --no-cache\n```\n\n3. run app container:\n\n```bash\ndocker compose -f docker-compose.yaml up -d\n```\n\n#### URL paths\n\nconvert endpoint\n\n```bash\nhttp://localhost:8080/api/v1/convert\n```\n\nswagger endpoint\n\n```bash\nhttp://localhost:8080/docs\n```\n\nredoc endpoint\n\n```bash\nhttp://localhost:8080/redoc\n```\n\n### Test Execution Flow\n\n1. run docker-compose.test.yaml:\n   ```bash\n   docker compose -f docker-compose.yaml -f docker-compose.test.yaml up -d\n   ```\n2. run test script:\n\n```bash\ndocker compose -f docker-compose.yaml -f docker-compose.test.yaml exec -it backend sh -c \"dos2unix /app/scripts/run_tests.sh \u0026\u0026 /app/scripts/run_tests.sh\"\n```\n\non linux use `sudo` prefix for previous commands\n\n# Project Structure Documentation\n\n```bash\n.\n|-- docker\n|   `-- Dockerfile                 # Specifies the environment to build a Docker image for the application.\n|-- docs\n|   `-- images\n|       |-- flowchart.png          # A PNG image of a flowchart illustrating project structure or logic.\n|       `-- flowchart.svg          # An SVG version of the flowchart for scaling purposes.\n|   `-- openapi\n|       |-- openapi.yaml        # An OpenAPI specification file defining API endpoints and their responses.\n|-- scripts\n|   `-- run_tests.sh               # A shell script to execute the test suite for the project.\n|-- src\n|   |-- conversion\n|   |   |-- __init__.py            # Marks the directory as a Python package; initializes the package.\n|   |   |-- dtos.py                # Contains Data Transfer Objects (DTOs) used in the application.\n|   |   |-- exceptions.py          # Defines exceptions used in the conversion process.\n|   |   |-- routers.py             # Defines API endpoint routes related to conversion functionality.\n|   |   |-- services.py            # Contains business logic and services for the conversion module.\n|   |   `-- value_objects.py       # Defines value objects, encapsulating domain-specific concepts.\n|   `-- main.py                    # Main entry point of the application.\n`-- tests\n    |-- conversion\n    |   |-- __init__.py            # Marks the directory as a Python package for test discovery.\n    |   `-- test_convert_endpoint.py  # Contains unit tests for conversion API endpoints.\n    `-- __init__.py                # Marks the directory as a Python package for test discovery.\n|-- Makefile                       # Automates tasks and builds using make commands.\n|-- README.md                      # Provides an overview of the project, setup instructions, and documentation.\n|-- docker-compose.test.yaml       # Configuration for setting up a Docker environment for testing.\n|-- docker-compose.yaml            # Configuration for setting up the main Docker environment.\n|-- env-example                    # Example of environment variable settings; template for actual `.env` file.\n|-- pyproject.toml                 # Configuration for Python project management and dependencies.\n|-- requirements-dev.lock          # Locked versions of development dependencies for reproducibility.\n|-- requirements.lock              # Locked versions of production dependencies for reproducibility.\n|-- ruff.toml                      # Configuration for Ruff, a linting tool to enforce code quality.\n```\n\n## Algorithm Explaination\n\n### Flow Chart\n\n![flowchart](docs/images/flowchart.png)\n\ncode related to this flow are located in the following path:\n\n```bash\nsrc/conversion/value_objects.py (Validations) and src/conversion/services.py (Conversion)\n```\n\n#### Flow Explanation:\n\n1. **Start**: The process begins with receiving the Roman numeral string as input.\n2. **Validation**: The input is validated:\n   - First, check if the input is a string (`Is input a string?`).\n   - Then, ensure all characters are valid Roman numerals (`Are all characters valid Roman numerals?`).\n3. **Conversion**: The valid Roman numeral string is mapped to integer values.\n4. **Comparison and Summation**:\n   - The current and next integer values are compared using the subtraction rule.\n   - The final sum is calculated.\n5. **Result**: The integer value is returned as the result.\n\n#### Error Handling:\n\n- If the input is not a string, a `TypeError` is raised.\n- If the input contains invalid Roman numeral characters, a `ValueError` is raised.\n\n## Tasks getting done `\u003ca name = \"tasks\"\u003e\u003c/a\u003e`\n\n* [X] create project structure\n* [X] install packages\n* [X] conversion project\n* [X] conversion service test\n* [X] conversion api test\n* [X] refactor project\n* [X] readme doc\n* [X] docker file\n* [X] docker compoes\n* [X] makefile commands\n* [X] create github repository\n* [X] ruff and pre-commit (Optional)\n\n## Git Conventions\n\n\"Conventional Commits\" guidelines:\n\nFormat: Each commit message should consist of three parts: a type, a scope, and a subject, separated by colons.\n\n```git\n\u003ctype\u003e(\u003cscope\u003e): \u003csubject\u003e\n```\n\n***Type* **: The type describes the kind of change that was made. It should be one of the following:\n\n- *feat*: A new feature\n- *fix*: A bug fix\n- *docs*: Documentation changes\n- *style*: Changes to formatting or whitespace, no code changes\n- *refactor*: Code refactor without any feature or bug fix\n- *test*: Adding or updating tests\n- *chore*: Updating build tasks, package manager configs, etc.\n- *ops*: affect operational components like infrastructure, deployment, backup, recovery, ...\n\n***Scope*** (optional) : The scope provides a hint at what part of the codebase the change affected. It's often omitted if the change is small or affects multiple parts of the codebase.\n\n***Subject*** : The subject is a brief description of the change, written in the imperative mood (e.g. \"Add\" instead of \"Added\").\n\n## GitFlow Workflow Conventions for FastAPI Project\n\n### Branching Model\n\n#### Main Branches\n\n- **main**:\n  - Contains the production-ready state of the codebase.\n  - **No direct commits**; only merges from `release` or `hotfix` branches.\n  - Tagged with version numbers for releases.\n\n- **develop**:\n  - The integration branch for features. It contains the latest development changes.\n  - Reflects the next release version.\n\n#### Supporting Branches\n\n- **feature/**:\n  - Naming convention: `feature/feature-name`\n  - Use for developing new features or enhancements.\n  - Branch off from: `develop`\n  - Merge back into: `develop`\n\n- **release/**:\n  - Naming convention: `release/version-number` (e.g., `release/0.1.0`)\n  - Used for release preparation. Allows for minor bug fixes and meta-data preparation for release.\n  - Branch off from: `develop`\n  - Merge back into: `main` and `develop`\n\n- **hotfix/**:\n  - Naming convention: `hotfix/fix-description` (e.g., `hotfix/fix-login-issue`)\n  - For quick fixes on production releases.\n  - Branch off from: `main`\n  - Merge back into: `main` and `develop`\n\n### Workflow Steps\n\n#### Starting a New Feature\n\n```bash\ngit checkout -b feature/my-new-feature develop\n```\n\n- Develop the feature, commit changes with meaningful messages.\n- Push the feature branch to the remote repository if collaboration is needed.\n\n#### Completing a Feature\n\n```bash\ngit checkout develop\ngit merge --no-ff feature/my-new-feature\ngit branch -d feature/my-new-feature\ngit push origin develop\n```\n\n#### Preparing a Release\n\n```bash\ngit checkout -b release/0.1.0 develop\n```\n\n- Update documentation, version numbers, and make any necessary tweaks.\n- Once ready, merge into `main` and `develop`.\n\n#### Finishing a Release\n\n```bash\ngit checkout main\ngit merge --no-ff release/0.1.0\ngit tag -a v0.1.0 -m \"Version 0.1.0\"\ngit checkout develop\ngit merge --no-ff release/0.1.0\ngit branch -d release/0.1.0\ngit push origin main develop --tags\n```\n\n#### Hotfix Workflow\n\n```bash\ngit checkout -b hotfix/issue-fix main\n```\n\n- Fix the issue, commit, then:\n\n```bash\ngit checkout main\ngit merge --no-ff hotfix/issue-fix\ngit checkout develop\ngit merge --no-ff hotfix/issue-fix\ngit branch -d hotfix/issue-fix\ngit push origin main develop\n```\n\n### General Conventions\n\n- **Commit Messages**: Should be descriptive. Use present tense (\"Add feature\" not \"Added feature\").\n- **Pull Requests**: Use for merging features into `develop` for code review, even if working alone.\n- **Testing**: Ensure all tests pass before merging into `develop` or `main`.\n- **Documentation**: Update relevant documentation with each feature or change.\n\n### CI/CD\n\n- **Continuous Integration**: Should run on pushes to `develop` and `main` to ensure code quality.\n- **Continuous Deployment**: Automate deployment from `main` branch to production after successful CI checks.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmdevpro78%2Froman_numeral_converter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmdevpro78%2Froman_numeral_converter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmdevpro78%2Froman_numeral_converter/lists"}