00 Example · Design doc
Design doc spec and plan
The spec and implementation plan of DD-0021, the fictional Lanefold tender-window change the homepage and use cases follow, with catalog mentions, an open question and planned changes.
No credit card required
01 Markdown
Copy the markdown
# DD-0021 Shorter tender window for API carriers
Fictional example from Lanefold, a made-up freight company. This is the same DD-0021 that the homepage demo and the tech lead and coding agent use cases follow. Names in double brackets link to catalog objects when an agent writes this over MCP; in the app, mention them with the @ picker.
## Spec
### Problem
Tenders to carriers wait 15 minutes for an acknowledgement before the load moves to the next carrier. The window was sized for EDI 204 tenders, whose acknowledgements arrive late (see ADR-0002, superseded by ADR-0003). Carriers connected through REST APIs acknowledge within seconds, so a 15-minute wait leaves API loads idle for most of the window.
### Decision
API carriers get 5 minutes to accept a tender. EDI carriers keep 15. [[Dispatch Service]] reads the window from the tender's channel at tender time, and [[Carrier Gateway]] tags each tender with the channel it went out on.
### Touches
- [[Dispatch Service]]: tender expiry per channel.
- [[Carrier Gateway]]: channel tag on every tender.
- [[Tracking Service]]: no change planned. The shipper countdown reads tender events as it does today.
### Risks
- A carrier migrating from EDI to a REST API may still acknowledge slowly during the switch. Mitigation: the channel is set per carrier and stays on EDI until the migration finishes.
- The shorter window raises re-tenders for slow API carriers. Watch re-tender counts per channel for two weeks after rollout.
### Open questions
- Q1: What happens when a carrier accepts after the window closes? Owner: Maya Chen. Until this is answered, late acceptance handling stays out of the plan.
### Rejected alternatives
- One shorter window for every carrier. Rejected because EDI acknowledgements routinely take more than 5 minutes (ADR-0002), so EDI loads would re-tender before the carrier had answered.
- Storing the window on each load at booking time. Rejected because a carrier's channel can change between booking and tender.
## Implementation plan
### Approach
Add a channel tag to the tender in [[Carrier Gateway]], then make the [[Dispatch Service]] tender timer read the window for that channel from configuration. A missing tag falls back to 15 minutes, never to 5.
### Planned changes
- [[Dispatch Service]]: expire API-carrier tenders after 5 minutes.
- [[Carrier Gateway]]: tag each tender with its channel.
### Tasks
- [ ] Per-channel tender window in Dispatch Service (api: 5, edi: 15, missing tag: 15). Owner: Priya Raman.
- [ ] Channel tag in Carrier Gateway on every outgoing tender. Owner: Claude Code, reviewed by Priya Raman.
- [ ] Late acceptance handling. Waits on Q1; unassigned until Maya Chen answers.
### Verification
- Tender expiry tests pass in CI for both channels and for the missing-tag fallback.
- A staging tender to an EDI carrier still waits 15 minutes.
- Each planned change above has a recorded change on this design doc by the person or agent who made it.
This example is fictional. Lanefold is a made-up freight company, and the services, people and pull requests in it don't exist. Use the shape, not the content.
Put it in ArchDocs
- Open Design docs in the sidebar and select New design doc. Give it a title and a location. Free includes one persistent design doc; Team and above include unlimited.
- Open Spec and paste everything under the Spec heading. Mention each service with the @ picker so it links to your catalog object; pasted names in double brackets stay plain text in the app.
- Add each item under Open questions as a question in Open questions, with its owner.
- Open Implementation plan and paste the plan section. Choose the objects it names under Planned changes.
Over MCP, an agent can do the same with create_design_doc, write_design_doc_variation for the spec with a brief, import_plan_file for the plan, add_design_doc_question for each question and set_planned_changes. Double-bracket names become catalog mentions when written that way. The design docs guide has the full workflow, and the brief fields for each variation match the headings in this example.
02 Start
Write the real one
No credit card required