Chhankitek Laravel Package

Technical Evaluation

Architecture fit

• asorasoft/chhankitek is a narrow domain utility, not infrastructure: AD→Chhankitek (Khmer lunar) date conversion. It belongs in a localization/i18n or "calendar & observance" bounded context, not in core domain models.
• Laravel fit depends on whether it ships a ServiceProvider/facade. Even if it does, treat the package as a replaceable adapter behind an internal LunarCalendarConverter interface so domain code never depends on the vendor's value objects or static facades.
• The real architectural value is not the conversion call — it is the rule engine (lunar day numbering, 29/30-day months, Athikameas leap-month insertion, Thithi leap-day handling). Confirm whether the package exposes those concepts or only a formatted string; a string-only API will force duplicate logic downstream.
• 0 dependents and 12 stars mean this is an unproven dependency; architect for substitution (interface + golden-file tests) from day one.

Integration feasibility

• Composer-installable, MIT-licensed — low legal friction, safe to vendor or fork if abandoned.
• Feasibility is gated on four verifications: PHP version constraint, illuminate/support constraint range, whether it works outside full Laravel bootstrap, and whether it handles timezone explicitly (Asia/Phnom_Penh, UTC+7).
• Last release 2026-09-02 is a future-dated tag relative to normal release cadence — verify this is a genuine release and not a metadata/clock anomaly or placeholder tag before pinning.
• No reverse conversion (Lunar→AD) is implied by the description; if the roadmap needs it (e.g., validating an entered observance date), that is custom work, not package work.

Technical risk

• Correctness risk is dominant and silent. A miscalculated leap month shifts an observance by ~30 days with no exception thrown. This is not a crash risk; it is a wrong-data risk in a culturally and (for public holidays) administratively sensitive domain.
• Unvalidated algorithm. No dependents means no production corroboration. Determine whether the rules are sourced from an authoritative Khmer calendar reference or reverse-engineered from a single dataset.
• Bus factor of one. Single maintainer, low visibility, no evidence of a review process, no CVE surface yet but also no scrutiny.
• Boundary risk: new-moon boundary handling, midnight/UTC+7 rollover, and leap-day naming conventions are the classic defect sites.
• Ecosystem drift risk: minor Laravel majors routinely break unmaintained illuminate/* constraints; with no maintainer activity this becomes a forced fork.

Key questions

1. Which PHP and Laravel/illuminate versions are declared, and is the constraint range actively tested?
2. What is the algorithm's provenance, and what fixtures/tests ship with it?
3. Does it return structured components (lunar day, month, year, leap flags) or only a display string?
4. Is timezone an explicit input, or does it defer to PHP's default?
5. Is there a Lunar→AD path, or a documented rule set we could implement ourselves?
6. What is the maintainer's stated support intent, and is the 2026-09-02 tag legitimate?
7. Does it cover the full range we need (historical backfill vs. forward scheduling), and how does it behave at range edges?

Integration Approach

Stack fit

• Fits a Laravel/PHP stack as a leaf dependency. Use it only in the presentation/localization layer or in a scheduling service, never inside pricing, billing, or identity logic.
• If the product is not Cambodia-facing, this is dead weight — the low opportunity score (22.36) reflects a narrow market. Scope it to Khmer localization, Cambodian holiday/festival features, or Cambodian-market compliance.

Migration path

1. Spike (1–2 days): install in a scratch branch, convert a reference set of 24–36 months, diff against an authoritative Khmer calendar source (government holiday gazette, a recognized almanac, or a domain expert).
2. Adapter: define LunarDateConverter interface in-house; implement ChhankitekAdapter wrapping the package. Nothing else imports the vendor namespace.
3. Golden-file test suite: commit fixture pairs (AD ↔ expected Chhankitek) covering leap months, 30-day months, year boundaries, and at least one known festival per year. These fixtures are the real asset — they survive a package swap or fork.
4. Dual-run: if an existing manual/Excel/legacy process exists, run both in parallel for one full observance cycle (≥12 months, ideally covering a leap year) and alert on divergence.
5. Fork-on-abandon trigger: documented threshold (no release or issue response for 6 months, or a blocking Laravel major) at which we take the MIT code in-house.

Compatibility

• Pin an exact version ("asorasoft/chhankitek": "x.y.z") — not ^ — until the algorithm is independently validated.
• Verify no transitive dependency conflicts with our Laravel major; check composer why-not before merge.
• Confirm behavior under our default timezone; if it silently uses date_default_timezone_get(), force Asia/Phnom_Penh inside the adapter and convert to UTC at the boundary.

Sequencing

• Sprint 1: spike + authoritative-source validation + go/no-go.
• Sprint 2: adapter, interface, golden-file tests, timezone handling.
• Sprint 3: read-only, non-transactional surface (display/calendar widget) behind a feature flag.
• Later: only after a clean parallel-run cycle, promote to scheduling/notification and any official-holiday logic.
• Parallel workstream: engage a Khmer-language/cultural reviewer early — they gate the go/no-go, not engineering.

Operational Impact

Maintenance

• Low code churn expected, but maintenance is effectively ours. Budget ~1–2 days/quarter for dependency-constraint checks and fixture re-validation, plus a one-time fork cost if the maintainer goes dark.
• Because we wrap it behind an interface, our maintenance burden is the fixtures and the adapter — small and bounded.

Support

• GitHub issues only; no SLA, no commercial backing, no security disclosure process. Escalation path is "read the source and patch it" — acceptable for a pure-computation library under MIT, unacceptable if the business expects vendor accountability.
• Establish an internal owner (name, not team) for this dependency in the service catalog to avoid orphaned-calc risk.

Scaling

• Conversion is CPU-cheap, pure, and stateless — no scaling concern for request-path use.
• Two real scale considerations: (a) cache computed lunar values for calendar-grid/range queries rather than converting in loops; (b) if used for batch generation (e.g., a year of observance notifications), precompute and persist rather than recompute per render.
• No external calls, no rate limits, no data residency implications.

Failure modes

• Silent wrong date (highest severity, lowest detectability) — mitigated only by golden-file tests + parallel run.
• Off-by-one day at midnight/UTC+7 or new-moon boundaries.
• Leap-month drift — an entire observance lands in the wrong month; user-visible and reputationally costly.
• Composer constraint conflict blocking a Laravel upgrade, forcing an unscheduled fork.
• Range-edge behavior (dates outside supported years) returning garbage rather than throwing.
• Abandonment — no security patches, no PHP-version updates.
• Each of these fails quietly; instrument with assertions and a divergence alert rather than relying on exceptions.

Ramp-up

• Engineering ramp-up: low (hours to first conversion, days to a hardened adapter).
• Domain ramp-up: moderate to high — the Khmer calendar's leap-month/leap-day rules are not intuitive, and engineers cannot self-validate output. A cultural/domain reviewer is a hard requirement, not a nice-to-have.
• Organizational ramp-up: document the "why" (algorithm provenance, validation method, known limitations) in an ADR alongside the adapter so the next engineer does not re-litigate the choice.

TPM recommendation: Adopt conditionally — as a pinned, interface-wrapped leaf dependency in a Cambodia/Khmer-facing feature, contingent on passing authoritative-source validation in the spike. Do not adopt for general-purpose date handling, and do not promote it to scheduling-critical or official-holiday logic until a full parallel-run cycle is clean.