srujanrana07/researchreach-a-cold-email-helper

1. Repository shape

- The repo is split into two top-level applications:

- app/: a Python backend, likely a Flask service.

- front/: a React single-page frontend.

- There is no obvious database, message queue, or worker system in the file tree; the architecture appears request-driven and stateless.

2. Frontend boundary

- front/src/App.js is the main client shell, with standard React bootstrap files in index.js, index.css, and test scaffolding.

- The frontend’s role is to collect user input, display matched papers, and show generated email content or status.

- It likely consumes backend HTTP endpoints directly; no separate frontend state service is visible.

3. Backend entrypoint

- app/app.py is the backend entrypoint and likely exposes the API surface for the UI.

- This is the orchestration layer: it would receive uploaded resumes or text, call the processing modules, and return ranked papers and email drafts.

4. Resume ingestion and extraction

- app/resume_processor.py is the first major processing boundary.

- Per the README, this stage extracts skills, projects, and other relevant text from resumes, likely from PDF input.

- This module is the bridge between raw user documents and the semantic matching pipeline.

5. Candidate text normalization

- The extracted resume content is condensed into a single “candidate profile text” used downstream.

- This flattened text is important because it becomes the semantic input for similarity matching against paper text.

6. Research paper acquisition

- app/paper_retrieval.py handles finding candidate papers.

- The README indicates paper discovery via Semantic Scholar / web scraping, and possible access to full text via Unpaywall.

- This is the external-data boundary: the backend depends on third-party scholarly APIs and web sources.

7. Semantic matching

- app/similarity.py performs the core ranking logic.

- The README specifies Sentence-BERT embeddings (all-MiniLM-L6-v2) and cosine similarity, so this module likely encodes both resume and paper text and scores their semantic closeness.

- This is the primary ML/NLP subsystem in the repo.

8. Email generation

- app/email_generator.py generates a cold email tailored to the selected paper and candidate profile.

- The README says this uses Gemini, so this module is an LLM integration boundary that turns structured match results into prose.

9. Email delivery

- app/email_sender.py is the outbound communication layer.

- It likely sends the generated email through SMTP or a mail API, separating drafting from actual delivery.

10. End-to-end data flow

- User interacts with the React UI → backend receives resume/input → resume text is extracted → papers are retrieved → resume and paper texts are embedded → cosine similarity ranks results → top match is returned → email draft is generated → optional email sending occurs.

- The central artifact moving through the system is text, transformed progressively from document content into embeddings, scores, and finally an email.

11. Testing and validation

- Backend-side testing appears in app/test.py.

- Frontend tests are set up via front/src/App.test.js and setupTests.js.

- This suggests the repo validates both the UI shell and backend logic, though no dedicated integration-test harness is visible.

12. Operational characteristics

- Dependencies are managed separately with app/requirements.txt for Python and front/package.json / package-lock.json for React.

- Because the visible architecture has no persistence layer, match results and generated emails are probably computed on demand rather than stored long-term.

- External services materially affecting the design are: Semantic Scholar, Unpaywall, and Gemini.