Repository Layout

Careers Engine follows a modular Python project structure. Source integrations, parsers, filtering, employment classification, storage, and publishing are organized into separate components, while tests, documentation, and automation workflows remain independently maintainable. The project also separates application code from persistent operational data through the careers-data repository.

Repository Structure

Explore the repository interactively. Expand any folder to inspect its files and subdirectories.

Application Code — src/careers_engine/

Find the source here: https://github.com/ZenYukti/careers-engine/blob/main/src/careers_engine The application package contains the implementation of the aggregation and publishing engine. Each component has a defined responsibility, allowing individual parts to evolve without requiring the entire pipeline to be rewritten. For the complete data flow, see the Ingestion Pipeline.

Scripts — scripts/

The scripts directory contains the application’s executable entry points for operational workflows. The main entry points are:

• collect.py: runs the collection and ingestion process.
• publish.py: runs the publishing process.

Keeping these entry points separate makes ingestion and publishing independently executable, both locally and through GitHub Actions. See the Running Locally guide for local execution instructions.

Tests — tests/

The test suite validates the behavior of the application’s components. Tests cover areas such as source adapters, parsers, eligibility filtering, employment classification, and other core logic. The separation of components makes it possible to test parsing, classification, and destination publishing independently of scheduled workflows and live delivery. The project uses Pytest for test execution, alongside Ruff for linting and formatting and Mypy for static type checking. See the Testing Guide for the project’s testing workflow.

Documentation — docs/

The documentation is organized by purpose rather than being maintained as one large guide. The documentation navigation is configured in docs/docs.json.

Automation — .github/workflows/

GitHub Actions workflows automate scheduled and manually triggered operations. The ingestion workflow runs the collection entry point and persists changes to the data repository. The publishing workflow selects unpublished opportunities independently for Discord and Telegram, attempts delivery through both publishers, and persists destination-specific publication history. Keeping orchestration in workflow definitions allows the application logic to remain executable independently of the CI environment. See the GitHub Actions guide for setup and execution details.

Persistent Data — careers-data

Persistent operational state lives in the separate careers-data repository. This separation prevents frequently changing generated data from being mixed with application source code. The workflows check out the data repository when they need to read or update its contents. See Storage Architecture for the persistence model and the responsibilities of each file.

Project Configuration

The root configuration files support development, dependency management, and quality checks.

• pyproject.toml defines project metadata, dependencies, and tool configuration.
• uv.lock records the resolved dependency versions.
• Makefile provides convenient commands for development and validation.

These files make the development environment and quality checks easier to reproduce.

Extending the Repository

When adding functionality, place it in the component that owns the relevant responsibility.

• Add a new upstream integration under sources/ and its corresponding parser where required.
• Add eligibility behavior under filters/.
• Extend employment classification in employment.py.
• Add company branding through the existing company registry and asset conventions.
• Add or update tests under tests/.
• Update the relevant documentation when behavior or developer workflows change.

Use the Adding a Source, Adding an Employment Rule, and Adding a Logo guides for component-specific instructions.

Next step

The architecture documentation now covers the system overview, ingestion, publishing, storage, company branding, employment inference, and repository organization. Continue with the Developer Guide to learn how to contribute changes and extend Careers Engine safely.