# roledesk A job-search engine for one person. It reads the public job boards of the companies you follow (Greenhouse, Lever, Ashby, Workable, SmartRecruiters, Recruitee, Personio) and runs saved searches on boards that span companies (Jobindex, Adzuna), keeps every posting with when it was first seen and when it closed, scores the open roles for each of your search agents, and tracks the applications you make. Built on the [boilerplate](../boilerplate): its job queue and scheduler (`pipeline/`), password (`auth/`) and deploy kit (`deploy/`), plus the plugin contract and tools from news (`desk/`). FastAPI, Jinja2, SQLite, `uv`, no build step. ## Quick start ```bash uv sync --all-extras uv run app companies seed # 362 European employers from seed/companies.json, 175 with a readable board uv run app job pull # read every board and search, embed and score them, extract the best, rescore, summarise uv run app serve # http://127.0.0.1:8790 ``` `uv run app worker` drains the queue without the web app, and `uv run pytest` runs the app's tests and the copied modules' own. `config.yaml` is the committed default, with one starter agent and four Copenhagen searches on Jobindex; `config.example.yaml` documents every key, including the `summarise:` block below. ## Sources: job boards and company boards The Sources sub-tab does all of this; the same actions exist on the command line: ```bash uv run app searches add jobindex "Copenhagen golang" --q "golang go-udvikler" --area 1 uv run app searches add adzuna "Berlin backend" --q backend --country de --where Berlin uv run app searches list uv run app companies prune --in DK,SE,NO,EU # lists; add --apply to unsubscribe uv run app companies discover "Pleo" pleo.io --add # find its board on its own site, then follow it ``` The seed is a hand-picked list of European tech employers, not a list of boards: a company whose careers site runs on something the app cannot read yet (Workday, SuccessFactors, Teamtailor, its own pages) is still a row, shown under Companies as "not readable yet" with a link to its careers page, so the gap is visible and one parser at a time closes it. `companies discover` reads a company's site for a link into one of the boards it knows, probes the hosts with a cheap per-slug endpoint when the pages link nothing, and with `--add` follows what it found the same way the seed does. A probe hit is a guess by name: check the roles it lists before trusting it for a common name. A Jobindex query is its own syntax: words are OR, `"a b"` is a phrase, `+word` is required; `--area 1` is Region Hovedstaden. An Adzuna search needs a free key from developer.adzuna.com in `ADZUNA_APP_ID` and `ADZUNA_APP_KEY`. `searches add` runs the search once and saves it only if it finds something. Switching a board or search off closes its open roles; the next pull after switching it back on reopens the ones it still lists. The `embeddings` extra is what `fit` needs, `agent` is for `extract` on a model, `passkeys` for the Account tab's passkeys. ## The tabs Two tabs, and a cog for settings. | | | |---|---| | **Roles** | newsdesk's feed: a filter rail (Show read, Best first or Newest first, first seen, tags, more filters), the open roles with company, place, age, tags and a summary, votes (▲ like ● neither way ▼ pass) and a Save button. A title opens the reader beside the list; on a phone it takes the screen. `j`/`k` move, `Enter` opens, `/` searches | | **Applications** | the saved roles and their status, each change recorded as an event | The cog opens `/settings`: a rail of pages on the left, the page beside it, sticky so Runs is one click away however long the company list gets. On a phone the rail is a strip under the header. | | | |---|---| | **Search agents** | a card per agent, newest first: name, an On/Off switch, what it looks for, and its weights. Edit turns the card into the form in place (name, intent, weights, require/prefer gates behind an Advanced disclosure); New agent puts a blank card on top. Saving or switching on rescores; deleting one takes its votes, liked companies and scores with it | | **Sources** | one page showing one section at a time, picked in the rail or by the URL fragment: job boards (queries on Jobindex or Adzuna: try, save, edit, remove), company boards (every company whose board is read, its open roles and its affinity for the picked agent, following a company, pruning boards by region) and runs (Pull now, what is running, the schedule, one stage at a time, and the message log) | | **Account** | the password, sessions and passkeys. Open on loopback, locked on anything else | Likes, hidden companies and votes belong to a search agent, not to the account: two agents rank the same roles differently, and one may hide a company the other favours. An agent also learns from votes: its `taste` weight scores a role by how close it is to the roles the agent liked minus the ones it passed. The reader, `/roles/{uid}`, shows the full posting: the same vote and Save controls, the company's own affinity, the tags and the summary when there is one. Opening a role marks it read, and so does a vote. A search role's posting is a teaser; the reader offers a Fetch button that scrapes the original listing once and stores the text. A Summarise button asks for a short summary of that one role; `config.yaml`'s `summarise:` block turns summarising on for the pull itself, bounded to the top `per_agent` roles of each agent so the cost stays flat. ## Docs - [`docs/decisions.md`](docs/decisions.md): what was decided for roledesk and why. - [`docs/open.md`](docs/open.md): what is left to do, for whoever picks this up next. - [`desk/README.md`](desk/README.md), [`pipeline/README.md`](pipeline/README.md), [`auth/README.md`](auth/README.md), [`deploy/README.md`](deploy/README.md): the copied modules, where each comes from and how to refresh it. - [`docs/hosting.md`](docs/hosting.md), [`docs/release.md`](docs/release.md), [`docs/server.md`](docs/server.md), [`docs/password-protection.md`](docs/password-protection.md), [`docs/llm-backends.md`](docs/llm-backends.md): the boilerplate's deployment docs.