{"id":13837451,"url":"https://github.com/jaimevalero/managing-awesome-lists","last_synced_at":"2026-01-18T02:06:04.252Z","repository":{"id":83479413,"uuid":"202490102","full_name":"jaimevalero/managing-awesome-lists","owner":"jaimevalero","description":"Utilities to find awesome resources","archived":false,"fork":false,"pushed_at":"2024-05-02T07:04:09.000Z","size":78095,"stargazers_count":16,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-05-28T08:08:57.091Z","etag":null,"topics":["awesome","awesome-list","lists","resources"],"latest_commit_sha":null,"homepage":"https://managing-awesome-lists.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/jaimevalero.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":"2019-08-15T06:55:25.000Z","updated_at":"2024-05-02T07:04:12.000Z","dependencies_parsed_at":"2023-06-04T09:15:13.541Z","dependency_job_id":"2518f2c6-030c-4a9d-872d-f0be4cbde81a","html_url":"https://github.com/jaimevalero/managing-awesome-lists","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaimevalero%2Fmanaging-awesome-lists","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaimevalero%2Fmanaging-awesome-lists/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaimevalero%2Fmanaging-awesome-lists/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jaimevalero%2Fmanaging-awesome-lists/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jaimevalero","download_url":"https://codeload.github.com/jaimevalero/managing-awesome-lists/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225653873,"owners_count":17502939,"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":["awesome","awesome-list","lists","resources"],"created_at":"2024-08-04T15:01:09.897Z","updated_at":"2026-01-18T02:06:04.242Z","avatar_url":"https://github.com/jaimevalero.png","language":"Python","funding_links":[],"categories":["Awesome List Trackers","HTML","HarmonyOS"],"sub_categories":["Windows Manager"],"readme":"# Awesome List Viewer\n\n**Discover and explore the best GitHub resources with Awesome List Viewer!**\n\n[Live Demo](https://managing-awesome-lists.vercel.app/)\n\n**Awesome List Viewer** is a backend utility for discovering and managing GitHub \"awesome lists\". It downloads metadata about curated awesome lists from GitHub, stores the data as JSON, and makes it available for querying through a dedicated frontend application.\n\n\n---\n\n## Features\n\n- **Automated Extraction:** Parses a configurable list of GitHub awesome lists, and extracts metadata (description, topics, stars, language, etc.) from each repository found.\n- **Efficient Storage:** Saves awesome list and repository metadata in structured JSON files, optimized for fast querying.\n- **Topic Categorization:** Groups repositories by topics for easier discovery.\n- **Frontend Integration:** Designed to power [the frontend app](https://managing-awesome-lists.vercel.app/) for user-friendly browsing and search.\n- **Easy Updates:** Can refresh all data with a single run, using your GitHub API token.\n\n---\n\n## How It Works\n\n1. **Fetch Awesome Lists:** The backend reads a list of awesome GitHub repositories from [`lists.txt`](lists.txt).\n2. **Download Metadata:** For each awesome list, it fetches the README, extracts repositories, and downloads metadata (stars, topics, etc.) via the GitHub API.\n3. **Store as JSON:** Metadata is saved in the `var/` directory (`var/awesome/`, `var/repo/`, `var/topic/`).\n4. **Frontend Consumption:** The generated JSON files are intended to be copied to the frontend repo (`managing-awesome-lists-frontend`) for browsing and querying.\n\n---\n\n## Directory Structure\n\n```\n.\n├── app.py                 # Main entry point: generates awesome lists and topic categories\n├── lists.txt              # List of awesome lists (one per line, GitHub URLs)\n├── requirements.txt       # Python dependencies\n├── var/                   # Generated JSON data (awesome lists, topics, repos)\n├── src/                   # Source code\n│   ├── categories/        # Category logic (Awesome, Topic)\n│   ├── downloaders/       # Tools for fetching repo/readme data\n│   ├── helpers/           # File management, utils\n│   ├── models/            # Data models (Awesome, Topic, Repo)\n│   ├── populators/        # Populator logic for awesome lists, topics\n│   └── serializers/       # Serialization/deserialization logic\n└── tests/                 # Unit tests\n```\n\n---\n\n## Usage\n\n### 1. Prerequisites\n\n- Python 3.10+\n- A GitHub API access token (for higher rate limits and private repo access)\n- `pip install -r requirements.txt`\n- Create a `.env` file with:  \n  ```\n  CREDENTIALS=your_github_token_here\n  ```\n\n### 2. Running the Backend\n\n```bash\npython app.py\n```\n\n- This will:\n  - Parse the lists in `lists.txt`\n  - Download metadata for each awesome list and its repositories\n  - Generate JSON files in `var/`\n  - Move/copy the relevant data to the frontend directory (as configured in `FileManager`)\n\n### 3. Connecting to the Frontend\n\nThe data is meant for the [Awesome List Viewer frontend](https://github.com/jaimevalero/managing-awesome-lists-frontend).  \nAfter running the backend, the JSON files are copied to the frontend's `public/` directory for use in the web app.\n\n---\n\n## Example: Adding a New Awesome List\n\n1. Add the GitHub URL to `lists.txt` (one URL per line).\n2. Run `python app.py` again to update the dataset.\n\n---\n\n## Data Model\n\nEach repository entry includes:\n\n- `full_name` – owner/repo\n- `description`\n- `topics` – list of topics\n- `created_at`, `pushed_at`\n- `stargazers_count`\n- `language`\n\nAwesome lists and topics are grouped and serialized for efficient frontend querying.\n\n---\n\n## Development\n\n- All logic is modularized in `src/` (see [src/README.md](src/README.md) for details).\n- Unit tests are provided in `tests/`.\n- Linting and type checking are recommended for code quality.\n\n### Run tests\n\n```bash\npython -m unittest discover -s tests\n```\n\n---\n\n## Contributing\n\nPull requests and issues are welcome!  \nIf you'd like to add new features or improve the code, please fork the repo and submit a PR.\n\n---\n\n## License\n\nThis project is released under the MIT License.\n\n---\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaimevalero%2Fmanaging-awesome-lists","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjaimevalero%2Fmanaging-awesome-lists","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjaimevalero%2Fmanaging-awesome-lists/lists"}