DropAFinder Engineering Documentation

This site is for engineers and contributors who have access to the three DropAFinder repositories. It assumes you can read code; it explains the why and the where, not the what a well-named function already conveys.

Start here

• Architecture overview — How the three codebases interact. Read this first.
• Run locally — Bring all three services up on your machine.
• Integration points — Every place the codebases talk to each other.

Codebases

Each codebase folder contains a directory-structure map, a routing/initialization page, and a conventions page that mirrors and expands the repo’s AGENTS.md.

Reference

• API endpoint catalog — Every route in the backend, grouped by resource.
• Data models — Eloquent models, key fields, and relationships.
• Shared types — TypeScript types in the Next.js app that mirror backend resources.
• Environment variables — All env vars across all three repos.

How-to (developer task-oriented)

• Add an API endpoint end-to-end — backend → next.js → optional widget. Recommended worked example for any new endpoint.
• Add a feature: frontend, backend, widget
• Add a customization option exposed in the builder
• Add a theme preset, map provider, autocomplete provider
• Test, Deploy

Architectural decisions

decisions/ is an ADR-style log capturing why the codebase looks the way it does. These are inferred from the code today; if you’re the author of a decision and disagree with the inference, please correct the relevant file.

Conventions

• Code references use the form path/to/file.ext:LINE-LINE. Paths are relative to the repo they belong to (e.g. src/lib/api/core.ts is in dropafinder-app-nextjs/).
• We do not paste source code as documentation. We explain what the code does and why, then show a clean illustrative snippet.
• Markers:
  • > 🟡 [SCREENSHOT: …] — a UI capture is pending.
  • > 🔴 [NEEDS CLARIFICATION: …] — the author needs an answer from a code owner.
• See _open-questions.md and _screenshots-needed.md for the consolidated marker backlogs.