docs: add Architecture Decision Records (ADR-001 to ADR-010)#4
Merged
Conversation
Record the architectural decision to keep frontend (React) and backend (FastAPI) in a single repository under separate top-level directories. Rationale: single developer, unified Docker Compose orchestration, and Demo Paper goal all favor monorepo over two separate repos. Full-stack feature changes are captured atomically in one PR, and a single `docker compose up` reproduces the entire system. - docs/decisions/ADR-001-monorepo-structure.md: new ADR with context, decision, rationale table, consequences, and rejected alternatives - CLAUDE.md: added ADR-001 reference note in Architecture section Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Rename docs/decisions/ → docs/adr/ to align with the labor-law-assistant project convention. Reformat ADR-001 and add nine new ADRs covering all major technology and architecture decisions for label-eval-portal. ADR list: - 001: Modular Monorepo (reformatted from original) - 002: Package managers — uv (backend) + pnpm (frontend) - 003: Backend framework — FastAPI - 004: Frontend framework — React + Vite (vs Next.js) - 005: Database — PostgreSQL 16 with JSONB for task configs - 006: Cache and message broker — Redis 7 (dual role) - 007: Async task execution — Celery with Redis broker - 008: Containerization — Docker + Docker Compose - 009: Testing strategy — pytest (≥80%/90% scoring) + Playwright E2E - 010: Config-driven architecture (NON-NEGOTIABLE, core contribution) Each ADR includes: context, candidates evaluated with comparison tables, decision, consequences (Easier/Harder), and alternatives rejected. Also update CLAUDE.md Architecture section to reference docs/adr/. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
All agents and developers must follow Red-Green-Refactor when writing tests. Agents must write the test file first, confirm it fails (Red), then implement the minimum code to pass (Green), then refactor. - ADR-009: added TDD Workflow section with agent-specific rules and a concrete scoring metric example (Red → Green → Refactor) - CLAUDE.md: updated Constitution principle 4 to explicitly reference TDD and link to ADR-009 Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Review Summary by QodoAdd Architecture Decision Records (ADR-001 to ADR-010) and establish ADR directory structure
WalkthroughsDescription• Add 10 Architecture Decision Records (ADR-001 to ADR-010) documenting all major technology and architecture decisions • Rename docs/decisions/ directory to docs/adr/ to align with project conventions • Update CLAUDE.md to reference ADR directory and enforce Test-Driven Development (TDD) for all agents • Each ADR includes context, evaluated candidates with comparison tables, decision rationale, and consequences analysis Diagramflowchart LR
A["Project Architecture"] --> B["10 ADRs Created"]
B --> C["ADR-001: Monorepo"]
B --> D["ADR-002: Package Managers"]
B --> E["ADR-003: FastAPI"]
B --> F["ADR-004: React+Vite"]
B --> G["ADR-005: PostgreSQL"]
B --> H["ADR-006: Redis"]
B --> I["ADR-007: Celery"]
B --> J["ADR-008: Docker"]
B --> K["ADR-009: Testing+TDD"]
B --> L["ADR-010: Config-Driven"]
M["CLAUDE.md Updated"] --> N["TDD Enforcement"]
N --> K
File Changes2. docs/adr/001-monorepo-structure.md
|
Code Review by Qodo
1.
|
![qodo-code-review[bot]](https://avatars.githubusercontent.com/in/484649?s=60&v=4){kind=small}
YAML example in ADR-010 used Chinese label display names ("疾病",
"症狀"), violating the English-first rule for all project artifacts
outside README.zh-TW.md.
Replaced with English equivalents ("Disease", "Symptom").
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
ADR-009: update coverage threshold paths to match CLAUDE.md canonical layout (backend/app/services/scoring.py, backend/app/api/routes/). ADR-010: fix broken Constitution relative link from .specify/... to ../../.specify/memory/constitution.md (correct from docs/adr/). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
singyichen
added a commit
that referenced
this pull request
Mar 25, 2026
- Remove 'prompt' from search.py docstring and core.py style keywords since it is not a supported --domain value (closes qodo issue #2) - Remove committed __pycache__/*.pyc files from git tracking - Add .gitignore with Python, Node, env, and IDE exclusions (closes qodo issue #4) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
singyichen
added a commit
that referenced
this pull request
Mar 25, 2026
- Allow zh-TW in prototype/ directory (CLAUDE.md rule update) [#1] - Fix login.html to apply persisted language on load instead of zh-TW [#2] - Add STRINGS[lang] guard in applyLang() to prevent crash on invalid lang [#3] - Extend applyLang() to localize aria-label attributes via data-i18n-aria-label [#4] - Add aria-label i18n keys to dashboard and login STRINGS objects [#4] - Qualify agent ownership paths with "when present" in CLAUDE.md [#5] Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
singyichen
added a commit
that referenced
this pull request
Apr 8, 2026
Covers spec #4 — two pages: /forgot-password (email submission with generic success message) and /reset-password (new+confirm password form with valid/expired/used token states and password mismatch validation). Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
singyichen
added a commit
that referenced
this pull request
Apr 9, 2026
design: wireframes and prototypes for forgot/reset password pages (spec #4)
6 tasks
singyichen
added a commit
that referenced
this pull request
Apr 10, 2026
CLAUDE.md: - Reduce SDD section from 62 lines to ~20 lines; remove pipeline table, status trigger list, and archive bash block (all now live in SKILL.md and specs/STATUS.md) - Keep only hard behavioral constraints: pipeline one-liner, TDD MUST NOT rule, pre-PR analyze gate, module names, design paths, status/archive pointers sdd-workflow SKILL.md: - Add /superpowers:brainstorm as first pipeline step with gate condition - Add STATUS.md update annotations at each pipeline stage - Mark /speckit.analyze as REQUIRED gate (was "optional") - Add archive step at pr-flow stage - Update Spec Directory Structure to show STATUS.md and _archive/ - Add /superpowers:brainstorm to Spec-Kit Commands table - Add new TDD Rule section with Red-Green-Refactor, applies-to scope, anti-rationalisation table, and restart instruction - Expand SDD Rules from 5 to 8: add TDD rule (#3), analyze gate (#4), archive on merge (#8) Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
singyichen
added a commit
that referenced
this pull request
Apr 14, 2026
* docs: add spec status index and archive convention
- Add specs/STATUS.md: single source of truth for all 16 feature pipeline
statuses, with status legend, feature table, and archive log
- Add specs/_archive/ directory for completed specs post-merge
- Update CLAUDE.md: add Spec Status Index section with required update
triggers, Spec Archive Convention with bash command, and two new rows
in Workflow Quick Reference table
Addresses weak document indexing and unclear completion status in spec-kit.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: strengthen SDD pipeline with brainstorm, TDD, and analyze gate
- CLAUDE.md: add full SDD pipeline table (8 stages with hard gates) at
the top of the SDD section, replacing vague /sdd-workflow reference
- CLAUDE.md: add TDD Rule section with mandatory language ("MUST NOT
write implementation before failing test") and explicit rejection of
common rationalisations
- CLAUDE.md: update Workflow Quick Reference — new feature row now shows
full stage sequence; add Pre-PR gate row requiring speckit.analyze
zero findings before every PR
- speckit.implement.md: step 4 upgraded from suggestion to REQUIRED gate
with anti-rationalisation list and restart instruction
- speckit.implement.md: add step 7 (mandatory /speckit.analyze gate,
must pass before PR); step 8 updates STATUS.md on completion
Addresses three SDD gaps identified from OpenSpec and Superpowers articles:
missing brainstorm entry point, unforced TDD, and optional analyze gate.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: slim CLAUDE.md SDD section and sync sdd-workflow SKILL.md
CLAUDE.md:
- Reduce SDD section from 62 lines to ~20 lines; remove pipeline table,
status trigger list, and archive bash block (all now live in SKILL.md
and specs/STATUS.md)
- Keep only hard behavioral constraints: pipeline one-liner, TDD MUST NOT
rule, pre-PR analyze gate, module names, design paths, status/archive
pointers
sdd-workflow SKILL.md:
- Add /superpowers:brainstorm as first pipeline step with gate condition
- Add STATUS.md update annotations at each pipeline stage
- Mark /speckit.analyze as REQUIRED gate (was "optional")
- Add archive step at pr-flow stage
- Update Spec Directory Structure to show STATUS.md and _archive/
- Add /superpowers:brainstorm to Spec-Kit Commands table
- Add new TDD Rule section with Red-Green-Refactor, applies-to scope,
anti-rationalisation table, and restart instruction
- Expand SDD Rules from 5 to 8: add TDD rule (#3), analyze gate (#4),
archive on merge (#8)
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: add 1→N iteration support to SDD workflow
- spec-template: add Version field, Spec Dependencies section (upstream/downstream), and Changelog section
- constitution: add iteration rule (update vs new spec), semantic versioning policy, and downstream impact requirement
- sdd-workflow SKILL: add Iteration Workflow (1→N) section and Cross-Spec Dependencies section
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* docs: add version, spec dependencies, and changelog to account specs 001-002
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: address PR #28 review findings
- specs/STATUS.md: clear stale branch and update notes for feature 012 (wireframe done via PR #27)
- speckit.implement: remove premature STATUS.md→done update; defer to pr-flow
- constitution.md: bump version to 1.3.0 and update Last Amended to 2026-04-13
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
* fix: address PR #28 review finding — fix agent-team ordering in workflow table
Move /agent-team before analyze gate in Workflow Quick Reference; it is an
implementation method, not a post-analyze step.
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
* fix: address PR #28 review findings
Co-Authored-By: Claude Haiku 4.5 <noreply@anthropic.com>
* docs: rewrite AGENTS.md as standard agent rules file
Replace agent directory catalog with a concise rules-focused format.
Reduces token consumption by ~65% (211 → 80 lines) by removing
redundant tables and replacing them with boundary constraints,
hard rules, and required behaviors for autonomous agents.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
* fix: address PR #28 review findings — align SDD pipeline across docs
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---------
Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
docs/adr/directory with 10 ADRs covering all major technology and architecture decisionsdocs/decisions/→docs/adr/to align with project conventionCLAUDE.mdto reference ADR directory and enforce TDD for all agentsADRs Added
Each ADR includes: context, candidates evaluated with comparison tables, decision, Easier/Harder consequences, and alternatives rejected.
Test Plan
docs/adr/(10 ADRs + README index)docs/decisions/removed (renamed todocs/adr/)CLAUDE.mdArchitecture section referencesdocs/adr/CLAUDE.mdConstitution principle 4 updated with TDD + ADR-009 link🤖 Generated with Claude Code