{"id":22933789,"url":"https://github.com/ivan-borovets/residency-explorer-local","last_synced_at":"2026-05-05T23:33:06.792Z","repository":{"id":254020959,"uuid":"841671931","full_name":"ivan-borovets/residency-explorer-local","owner":"ivan-borovets","description":"Locally hosted web app that simplifies managing data about medical residency programs in the US","archived":false,"fork":false,"pushed_at":"2024-08-25T15:19:30.000Z","size":1894,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-08-14T04:11:48.449Z","etag":null,"topics":["alembic","docker","match","medicine","nrmp","postgresql","python","residency","sqlalchemy","starlette-admin","usmle"],"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/ivan-borovets.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}},"created_at":"2024-08-12T21:26:40.000Z","updated_at":"2025-03-30T19:38:41.000Z","dependencies_parsed_at":"2025-02-07T12:11:58.597Z","dependency_job_id":"290c1f72-92ac-4da2-98e1-a1913c06ee67","html_url":"https://github.com/ivan-borovets/residency-explorer-local","commit_stats":null,"previous_names":["ivan-borovets/residency-explorer-local"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ivan-borovets/residency-explorer-local","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivan-borovets%2Fresidency-explorer-local","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivan-borovets%2Fresidency-explorer-local/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivan-borovets%2Fresidency-explorer-local/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivan-borovets%2Fresidency-explorer-local/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ivan-borovets","download_url":"https://codeload.github.com/ivan-borovets/residency-explorer-local/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ivan-borovets%2Fresidency-explorer-local/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32672675,"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":["alembic","docker","match","medicine","nrmp","postgresql","python","residency","sqlalchemy","starlette-admin","usmle"],"created_at":"2024-12-14T11:34:37.675Z","updated_at":"2026-05-05T23:33:06.768Z","avatar_url":"https://github.com/ivan-borovets.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Residency Explorer Local\n\n**residency-explorer-local** is a locally hosted web app that simplifies\nmanaging data about medical residency programs in the US, aiding prospective\nresidents in making informed decisions during the Residency Match process.\n\n![ProgramOverview](media/01ProgramOverview.png)\n![DirectorOverview](media/02DirectorOverview.png)\n\n## Features\n\n- **User-Friendly Data Entry**: Easily input information about medical\n  residency programs through intuitive forms.\n  ![ProgramCreate](media/03ProgramCreate.png)\n  ![ProgStatCreate](media/04ProgStatCreate.png)\n  ![DirectorCreate](media/05DirectorCreate.png)\n\n- **Table View**: Data is presented in well-organized tables, making it easy\n  to review and manage.\n  ![Programs](media/06Programs.png)\n  ![ProgramStat](media/07ProgramStat.png)\n  ![DirectorsAnn](media/08DirectorsAnn.png)\n  ![Peers](media/09Peers.png)\n\n- **Instant Filtering and Sorting**: Real-time data filtering and sorting\n  within tables, no page reload needed.\n  ![](media/10SortedPO.png)\n  ![](media/11OrderedPOAnn.png)\n\n## Installation and Setup (for Windows users)\n\n1. Install [Docker Desktop](https://www.docker.com/products/docker-desktop/).\n2. Generate the `.env` file. This step is required only once during the\n   installation.\n\n   2.1. Open `PowerShell`\n\n   2.2. Navigate to the root directory of the project\n\n   2.3. Run\n      ```bash\n      python ./scripts/generate_dotenv/dotenv_from_toml.py\n      ```\n\n   \u003e Unfortunately, you will need to figure out how to install Python if you don't have it already.\n\n   \u003e Alternatively, you can use **an unsafe method**: simply rename `.env.example` to `.env` in the root directory of\n   the project.\n\n## Running the Application (for Windows users)\n\n### First-Time Launch\n\n1. Ensure the `.env` file is present in the root directory of the project.\n2. From the root of the project, open PowerShell and run the following command:\n\n```bash\ndocker compose up --build\n```\n\nThis will build and start the application. Once the application is ready,\nyou will be prompted to visit [0.0.0.0:8888](http://0.0.0.0:8888) in your browser.\n\n### Subsequent Launches\n\nAfter the first launch, you can start and manage the application directly\nfrom `Docker Desktop`.\n\nOpen `Docker Desktop` and navigate to the `Containers` section.\nYou will find a shortcut to start the application under the\n`residency-explorer-local` container.\nAfter starting the container, you can click on the link labeled `8888:8888`\nto open the application in your browser.\n**It is recommended to stop** the application in `Docker Desktop` when\nyou're done using it to free up system resources.\n\n![DockerAnn](media/12DockerAnn.png)\n\n## How to Use\n\n1. Create a Program in the `Programs` Section.\n2. Once a Program is created, you can add associated statistics in the `Program statistics`\n   section and assign a director in the `Directors` section.\n3. After a director is added, you can further enrich the data by adding peers (colleagues)\n   in the `Directors' Peers` section and alumni in the `Directors' Alumni` section.\n\n### **Q: Why this order?**\n\n\u003e **A:** Adding a director without a program, or peers without a director, is meaningless.\n\nSummary information about the programs will be displayed in the `Program Overview`, and summary information about\ndirectors will be available in the `Director Overview`. These are convenient tables for searching and sorting\ninformation.\n\n**Each table can be exported to CSV, Excel, or PDF.** For the highest quality PDF export, it is recommended to use\nthe `Print` option and save as PDF.\n\n![Export](media/14Export.png)\n\nThe `Predefined` tab contains pre-filled auxiliary tables. You can edit these tables as needed. However, it is\nrecommended not to delete rows that are linked to other tables, as this may cause those linked entries to be deleted as\nwell.\n\n## For Developers\n\n### Stack\n\n#### Backend:\n\n- `Python 3.12`: Core programming language for the app.\n- `Uvicorn`: ASGI server for running the app.\n\n#### Database:\n\n- `PostgreSQL`: Relational database for data storage.\n- `SQLAlchemy`: ORM for database interactions.\n- `Psycopg2`: Synchronous PostgreSQL adapter for Python.\n\n\u003e Because `starlette-admin` seem not to support async engines\n\n- `Alembic`: Database migrations tool for SQLAlchemy.\n\n#### Data Management:\n\n- `Pydantic`: Data validation and type checking.\n- `Pydantic-Settings`: Handling of env variables and settings.\n- `Rtoml`: TOML configuration file parser.\n\n#### Admin Interface:\n\n- [`Starlette-admin`](https://github.com/jowilf/starlette-admin): Provides a web interface for managing the database.\n\n### Database schema\n\n![Database Schema](media/13ERD_Residency.png)\nThis diagram was created using [dbdiagram.io](https://dbdiagram.io).\nThe database schema code is available in the `./docs/database_schema.dbml`\nfile.\n\n### Customization\n\nThe primary configuration file for the application is `config.toml`.\nAfter making any changes to this file, you must generate a new `.env` file.\nThis can be done using\n\n```bash\npython ./scripts/generate_dotenv/dotenv_from_toml.py\n```\n\nAlternatively, you can use the following `Makefile` command to generate the `.env` file:\n\n```bash\nmake dotenv\n```\n\nIt's important to ensure that the `.env` file is correct, as only with\na properly configured `.env` will the\n\n```bash\ndocker compose up --build\n``` \n\nfunction correctly. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivan-borovets%2Fresidency-explorer-local","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fivan-borovets%2Fresidency-explorer-local","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fivan-borovets%2Fresidency-explorer-local/lists"}