# Application Tracker

Application Tracker is a self-hosted workspace for recording job applications,
documents, follow-up actions, contacts, and outcomes. It combines a responsive
web interface with optional local and authenticated remote Model Context
Protocol (MCP) access.

The application stores its data in SQLite and, by default, sends no workspace
content to a hosted service. The optional Outlook evidence integration sends
bounded company, role, and posting searches to Microsoft Graph and reads only
the configured mailbox. A fresh installation contains no account, sample data,
or default password.

## Features

- Dashboard metrics, searchable Opportunities and applied-only Applications
  views, separate end-company and agency fields, salary, rating, and work
  arrangement columns, sortable tables, detail drawers, modal editing,
  contacts, links, due actions, and immutable history
- Configurable statuses, sources, role types, and document types
- Local administrator and member accounts with revocable sessions
- Original document storage, SHA-256 deduplication, application associations,
  inline PDF viewing, bounded DOCX and email previews, and safe downloads
- Bounded email-link extraction, plus optional server-side Microsoft Graph
  synchronization that finds and verifies Outlook evidence for one known
  application without storing email bodies
- Local stdio MCP and authenticated Streamable HTTP MCP with bounded application
  and document transfer, explicit actor binding, website-controlled write
  access, and immutable audit events
- Built-in remote MCP OAuth using local accounts, plus administrator-managed
  client IDs and one-time bearer tokens and optional external token verification
- Online SQLite backup, verification, non-overwriting restore, and forward
  migrations

Application Tracker does not yet provide OpenID Connect browser login. Local
password login always remains available.

## Security model

- First-run setup requires an operator-generated one-time token.
- The project never creates `admin/admin` or another known credential.
- Passwords use salted, memory-hard scrypt hashes; random session and MCP tokens
  are stored only as hashes.
- Every application, document, user, and MCP operation preserves workspace and
  role checks in shared application services.
- Runtime secrets, databases, backups, and machine configuration remain outside
  Git and container images.

Read the [product contract](docs/product-contract.md),
[architecture](docs/architecture.md), and [security model](docs/security-model.md)
for the complete boundary.

## Requirements

- Node.js 22.12 or newer for a direct installation
- Docker Engine with the Compose plugin for a container installation
- A trusted HTTPS reverse proxy for Internet access

## Quick start for development

```sh
cp .env.example .env
npm ci
npm run dev
```

Open `http://<server-ip>:5173`, replacing `<server-ip>` with an address assigned
to the host. The development server and backend listen on all interfaces for
LAN and container access. Restrict both ports with the host firewall, and never
use Vite as a public reverse proxy.

Generate a setup token with `openssl rand -hex 32`, place it in `.env`, and
follow the [initial administrator setup](docs/initial-setup.md). Remove the token
and restart the service after setup succeeds.

Run every local quality gate with:

```sh
npm run check
```

## Deploy

Choose one supported path:

- [Run the compiled service directly on a Linux host](docs/local-deployment.md)
- [Build and run the hardened Docker Compose example](docs/container-deployment.md)

Both guides keep data and secrets outside the checkout. The container example
publishes port 3333 on loopback by default; LAN exposure requires an explicit
override. Internet exposure requires HTTPS at a trusted reverse proxy.

Before upgrades, create an online backup and follow the
[backup and restore runbook](docs/backup-restore.md). Copying a live WAL database
file is not a valid backup.

## MCP

Local clients should follow the [stdio guide](docs/local-mcp.md). Remote clients
should follow the [authenticated HTTPS guide](docs/remote-mcp.md).

Settings → Connections provides copyable templates for Claude.ai, remote Codex, local
Codex, and Claude Desktop. Remote interactive clients use the built-in OAuth
flow and the same local username and password as the website; no Authentik or
other external identity provider is required.

Fresh workspaces are read-only through MCP. An administrator can enable
**Read and write** under **Settings → Connections**. The server rechecks this
policy on every mutation, including calls made through existing sessions.

### Example prompts for ChatGPT.com

After connecting Application Tracker to ChatGPT.com, try prompts such as:

```text
Using Application Tracker, give me a read-only summary of my open
opportunities. Group them by stage and include the end company, agency, role,
salary, rating, work arrangement, and next action. Put overdue actions first.
```

```text
List only the opportunities I have applied for, meaning records with an applied
date. Sort them by rating from highest to lowest and show the end company,
agency, role, salary, work arrangement, stage, and applied date. Do not change
anything.
```

```text
Find my open remote or hybrid opportunities rated 4 or 5. Recommend the five I
should focus on next, using the recorded salary, stage, next action, and notes.
Tell me which important fields are missing.
```

When MCP write access is enabled under **Settings → Connections**, ChatGPT.com can also
create or update records:

```text
Create an opportunity for Senior Product Designer at Example Studio. The agency
is Example Recruitment, the salary is £75,000–£85,000, the rating is 4, and the
work arrangement is hybrid. Use the Prospect stage and leave the applied date
empty. Show me the completed record before making any further changes.
```

After the server encryption key is configured, an administrator can add, test,
edit, disable, or delete named Outlook connections under **Settings →
Connections**. Assign each application to its originating connection before
synchronizing it:

```text
For Application Tracker application <application-id>, synchronize Outlook email
evidence. Use the single sync_outlook_email_evidence tool and do not call a
separate Outlook or Microsoft 365 connector.
```

To process only new mail since a connection's last successful pass:

```text
Recheck the russ@sargeson.co.uk Graph connection for new job-search emails
since its last successful reconciliation. Use only
reconcile_outlook_graph_connection and report every linked, ambiguous,
conflicting, and unmatched message. Repeat with the same connection while
reconciliation.hasMore is true.
```

To inspect a digest reported by that pass without exposing its body to the MCP
client:

```text
Using only Application Tracker, process the Outlook job digest with RFC
Message-ID <digest-message-id> from the russ@sargeson.co.uk Graph connection.
Use process_outlook_job_digest, inspect every result page, and do not create or
update opportunities.
```

To search backward without exposing mailbox content to another connector:

```text
Using only Application Tracker, call search_outlook_job_digests for the
russ@sargeson.co.uk Graph connection over a fixed seven-day window. Follow its
exact offsets and continuation cursors, then process only messages classified
marketing_or_digest using their exact returned RFC Message-IDs.
```

The one-application tool reads the application, validates existing evidence,
searches the configured `Inbox\Jobs` folder, retrieves and scores a bounded
shortlist, links only a sufficiently confident RFC Message-ID, and verifies the
stored evidence before returning. The digest tool retrieves one exact message
inside Application Tracker, resolves its job links, inspects structured posting
metadata in pages of five, and reports deterministic tracker matches. Provider
JSON-LD is preferred; a provider challenge can use only an explicitly paired,
unambiguous employer/title from the same bounded digest card and reports that
provenance. It also reports whether digest fallback was attempted and a stable
reason when it was unavailable. It returns no email body and changes neither
Outlook nor application records. See the
[operator setup guide](docs/outlook-email-sync.md).

### Job-email agent skill

The repository includes the installable
[Application Tracker Job Email](.agents/skills/application-tracker-job-email/SKILL.md)
skill. For a known application, it teaches compatible AI clients to use only
`sync_outlook_email_evidence`; the Application Tracker server owns the Graph
reads, scoring, evidence link, and read-back verification. No separate
Microsoft 365 MCP is required for that path.

The skill uses `search_outlook_job_digests` for bounded, resumable historical
discovery and `process_outlook_job_digest` when one exact digest RFC Message-ID
is known.
It retains its connector-orchestrated flow for broader
Jobs-folder discovery and attachment import. Those workflows still discover an
already-connected Softeria-compatible Microsoft 365 surface and never install
or launch one silently.

Codex discovers the skill from `.agents/skills` while working in this checkout.
Other clients that support `SKILL.md` skills can install the
`.agents/skills/application-tracker-job-email` directory using their normal
skill installation flow. The server-side one-application path needs only
Application Tracker. Connect a Softeria-compatible Microsoft 365 MCP as well
only for a broader folder or attachment workflow.

## Documentation

- [Development standards](docs/development.md)
- [Database and migrations](docs/database.md)
- [Documents and previews](docs/documents.md)
- [Reference lists](docs/reference-lists.md)
- [User management](docs/user-management.md)
- [MCP status](docs/mcp-status.md)
- [Server-side Outlook evidence sync](docs/outlook-email-sync.md)
- [MCP data transfer](docs/mcp-data-transfer.md)
- [Capability checklist](docs/parity-checklist.md)

## Contributing and security

Contributions are welcome through pull requests. Read
[the contribution guide](.github/CONTRIBUTING.md) before submitting code.
Report suspected vulnerabilities through the private process in the
[security policy](.github/SECURITY.md), not a public issue.

## License

Application Tracker is source-available under the [Elastic License 2.0](LICENSE).
You may use, modify, and redistribute it, but you may not provide the software
to third parties as a hosted or managed service that exposes a substantial set
of its features.