offerflow README

The project's README from github.com/Xiangyahaian/offerflow. As one markdown file: README.md.

OfferFlow

License: MIT Python FastAPI

核心亮点:AI 解析求职邮箱。
绑定你的邮箱(IMAP)并配置 AI 模型后,OfferFlow 会自动读取笔试 / 面试 / Offer 等邮件,抽取公司、岗位、时间与状态,并回填到投递表——不用再手动抄邮件内容。

在此之外,它还是一套本地优先的实习 / 校招投递管理工具:表格跟踪进度、面试倒计时与日历视图,数据存在本机 SQLite,无需注册登录。

校招投递页面截图

Features

Tech Stack

Layer Stack
Backend FastAPI · SQLAlchemy · SQLite
Frontend Jinja2 · 原生 JS / CSS
Runtime Python 3.10+ · Uvicorn

Quick Start

Requirements

Run locally

git clone https://github.com/Xiangyahaian/offerflow.git
cd offerflow

python -m venv .venv
# Windows
.\.venv\Scripts\activate
# macOS / Linux
source .venv/bin/activate

pip install -r requirements.txt
cp env.example .env   # Windows: copy env.example .env

# optional: load sample applications
python scripts/seed_demo.py

python run.py

Open http://localhost:8001

Run with Docker

docker compose up -d --build

App: http://localhost:8001
Database file: ./data/offerflow.db

Configuration

Copy env.example to .env and adjust as needed:

Variable Default Description
PORT 8001 Server port
DATABASE_URL sqlite:///./offerflow.db SQLite path
ENV development Use production to disable reload and /docs
SECRET_KEY (example) Used to encrypt IMAP / AI API keys

启用 AI 邮箱解析(核心功能): 在侧边栏打开邮箱 / AI 助手页面,填写 IMAP 账号与 AI 模型 API Key;之后即可自动拉取并解析求职邮件。SECRET_KEY 用于加密这些凭据。

Project Structure

offerflow/
├── run.py                 # entrypoint
├── requirements.txt
├── env.example
├── Dockerfile
├── docker-compose.yml
├── backend/               # FastAPI app, models, routers
├── frontend/              # templates + static assets
├── scripts/seed_demo.py   # sample data
└── docs/screenshots/      # README screenshots

API

With ENV=development, interactive docs are available at /docs.

Endpoint Description
/api/campus Campus applications
/api/internships Internship applications
/api/dashboard/stats Dashboard stats
/api/mail Mailbox / IMAP
/api/ai-assistant Mail AI parsing

Contributing

Contributions are welcome. See CONTRIBUTING.md for guidelines.

  1. Fork the repository
  2. Create your branch (git checkout -b feature/awesome)
  3. Commit your changes
  4. Open a Pull Request

License

Released under the MIT License.

offerflow (Xiangyahaian/offerflow)

Searching Database…

What is this?OfferFlow is a local-first tracker for internship and campus job applications — it also connects to your inbox and uses AI to turn job emails into application records.
Is it a hosted service I sign up for, or something I run myself?You run it yourself: a FastAPI server with a browser UI built on Jinja2 and vanilla JS/CSS, started locally or via Docker — there is no hosted version.
How do I get it running?Run it with Python 3.10+ or Docker Compose. Copy env.example to .env first; the server listens on port 8001 by default.
What do I need for the AI email parsing to work?Your own IMAP account and an AI model API key, entered on the Mailbox / AI Assistant page in the sidebar; a SECRETKEY in your .env encrypts those credentials.
Do I have to connect a mailbox, or is it useful without the AI part?The tracker, dashboard and calendar work on their own; AI parsing is an extra you switch on later from the Mailbox / AI Assistant page once it has an IMAP account and API key.
Is it free to use?Yes — it is MIT licensed, so you can use, modify and self-host it freely; there are no paid plans.
What does the AI actually do with the emails it finds?It pulls application emails over IMAP, extracts the company, role, time and status, and automatically creates or updates the matching application record — no manual copy-pasting.
What can I track for each application?Status transitions, priority, interview rounds and a countdown to each interview, plus drag-and-drop reordering and batch operations on the applications table.
Besides the applications table, what other views are there?A dashboard showing total applications, pending items and an offer overview, plus a calendar view that gathers all written tests and interviews in one place.
What is it built with?FastAPI with SQLAlchemy over SQLite on the backend, a Jinja2 frontend in vanilla JS and CSS, running on Python 3.10+ under Uvicorn.
Size
1 MB
Stars
246
Updated
CommitAug 17
Age
2mo
Commits · 90 Days