Back to Glossary

ADR

ADR

سجل قرار الهندسة

GLS-000151

Intermediateengineering1 min read
architecture decision recorddecision recordarchitectural decisiondesign decision doc
Sign in to save & take notes

Definition

A short document recording an important architectural decision — what was decided, why, and what alternatives were rejected.

وثيقة قصيرة تُسجِّل قرارًا هندسيًا مهمًا — ما الذي قُرِّر ولماذا وما البدائل التي رُفِضت.

Why It Matters

Without ADRs, new team members (or future-you) have no idea why the codebase is structured the way it is. ADRs prevent revisiting settled decisions.

بدون ADRs، أعضاء الفريق الجدد (أو أنت في المستقبل) ليس لديهم أي فكرة عن سبب هيكلة قاعدة الكود بالطريقة التي هي عليها. ADRs تمنع إعادة النظر في القرارات المحسومة.

Full Definition

An Architecture Decision Record (ADR) documents significant technical decisions: what the team chose, why they chose it, what alternatives were considered, and what consequences are expected. Format: Status, Context, Decision, Consequences. ADRs live in the docs/architecture/ directory and are stored with the code. 404Fault uses ADRs to document major choices (Why Firestore? Why Vercel? Why embedded slugs for Knowledge Graph?).
سجل قرار الهندسة (ADR) يُوثِّق القرارات التقنية المهمة: ما اختاره الفريق ولماذا وما البدائل التي نُظِر فيها وما العواقب المتوقعة. الصيغة: الحالة والسياق والقرار والعواقب. تعيش ADRs في مجلد docs/architecture/ وتُخزَّن مع الكود. يستخدم 404Fault ADRs لتوثيق الاختيارات الكبرى (لماذا Firestore؟ لماذا Vercel؟ لماذا slugs المضمّنة لـ Knowledge Graph؟).

Example Usage

“ADR-015 in 404Fault documents: Decision: use embedded prerequisiteSlugs/nextStepSlugs arrays on each term rather than a separate knowledge_graph_edges collection. Why: simpler queries, no joins needed.”

“ADR-015 في 404Fault يُوثِّق: القرار: استخدام مصفوفات prerequisiteSlugs/nextStepSlugs المضمّنة في كل مصطلح بدلًا من مجموعة knowledge_graph_edges منفصلة. لماذا: استعلامات أبسط، لا حاجة للوصلات.”

Knowledge Graph

AI Builder Tips

Sign in for more features

Avoid these mistakes when using ADR:

1

Writing ADRs after the fact as documentation (ADRs are most useful when written at decision time)

2

Making ADRs too long — one page is usually enough

Sign in to unlock guided AI explanations from AI Teacher.

Generate a Prompt

Copy this prompt and use it directly with any AI model — no setup needed.

Ready-to-Use Prompt
Help me build a project using ADR.

Explain:
1. What is ADR and why it matters
2. The core architecture and required tools
3. Step-by-step implementation plan
4. Common mistakes to avoid: Writing ADRs after the fact as documentation (ADRs are most useful when written at decision time), Making ADRs too long — one page is usually enough
5. Best practices and production tips

Official Resources

No official documentation link on file for ADR yet.

Browse all AI termsCreate free account