Laravel Daily Activity Laravel Package

Technical Evaluation

Architecture fit

• The package stores daily activity as a 46-byte annual bitmap (366 bits) per subject per year, keyed to an Eloquent polymorphic subject. Compared with a row-per-day design (~365 rows and tens of KB per subject-year), this is a 2–3 order-of-magnitude storage reduction and turns "did the user check in today?" into a single bit read.
• The trade-off is opaqueness to SQL. There is no per-day metadata (timestamp, source, notes, device) and no way to do ad-hoc GROUP BY date analytics against this table. All reporting must go through the package's query API. If we have or anticipate a BI/warehouse need for daily activity facts, this table can store the materialized state but cannot be the system of record.
• The API surface is well matched to typical product asks: calendar view, activity-day counts (range / week / month), current streak, longest streak, plus backfill for retroactive check-ins. Polymorphic subjects mean we can attach activity to User, Team, or Device without schema changes.
• Write path is correctly designed for a check-in workload: per-day dedupe makes marking idempotent, and cache invalidation is tied to transaction commit with concurrency protection — the standard correct pattern for cache-plus-write.

Integration feasibility

• Installation is the standard three-step Laravel flow (composer require → vendor:publish → migrate) and is purely additive: one new table, no alterations to existing tables. Reversible by dropping the table.
• Constraints are hard: PHP 8.3+, Laravel 12/13. We must confirm our runtime matrix before committing; if any production service is on Laravel 10/11 or PHP 8.1/8.2, adoption is blocked for that service.
• Claimed DB support is SQLite/MySQL/PostgreSQL, which suggests bitmap arithmetic happens in PHP rather than via vendor-specific bit functions. Worth confirming, since that is the assumption that makes portability real.

Technical risk

• v1.0.0 with a single-maintainer namespace is the dominant risk. No upgrade history, no evidence of a test matrix or CI in the notes, and the public API should be treated as unstable until a 1.x track record exists. Mitigation: pin the version, vendor/fork the repo, and wrap it behind our own service class.
• Streak correctness is the highest-value logic and the most intricate: current streak reads years on demand, longest streak uses a byte lookup table scan, and both must handle cross-year boundaries, leap years, and app timezone. The shipped performance-comparison script is a good signal but is not a correctness proof.
• Timezone semantics: day boundaries follow the application timezone, not the user's. For a global user base this is a product-visible correctness issue (a user in UTC+8 checking in at 07:00 local may land on the previous day).
• Granularity lock-in: migrating away from the bitmap to row-level events later is a one-way door unless we already retain raw event data elsewhere.
• Key questions:
  1. What is the documented test coverage and CI status, and how are DST/midnight/leap-day edges tested?
  2. Do the perf scripts show numbers at our target scale (e.g., 100k subjects × 5 years), for both streak queries and concurrent writes?
  3. Is per-user timezone override supported or planned, or is app timezone the only lever?
  4. What happens on concurrent marks of the same day by different processes — row lock, optimistic retry, or silent last-write-wins?
  5. Is raw event history retained anywhere, or is the bitmap the only record?
  6. Documentation language and issue-tracker responsiveness — can the team self-serve?

Integration Approach

Stack fit

• Fits cleanly if we are on Laravel 12/13 and PHP 8.3+. The package is a leaf dependency: one table, one trait/interface on the subject model, no service-provider gymnastics, no queue or external service requirement.

Migration path

• Additive migration only; no data backfill is required to start. Initial adoption can be scoped to a single subject type and a single feature surface (e.g., "current streak" badge) while existing activity logic keeps running.
• Backfill is a first-class feature, so historical check-ins from an existing events table can be replayed day-by-day without a custom migration script. That materially de-risks adoption and gives us a natural parallel-run comparison.

Compatibility

• Verify: our PHP/Laravel versions across all services that would use it; the cache store (must be shared across app servers — Redis, not array/file); queue workers' afterCommit semantics if marking happens inside jobs; and whether the custom-activity-model and cache-prefix options are needed for multi-tenancy.
• Confirm the migration is idempotent and safe to run in a rolling deploy alongside old code (it should be, being a new table).

Sequencing

1. Version-matrix check against our services; confirm no PHP/Laravel blockers.
2. Non-production spike on one subject type, using the custom model + cache prefix to match our conventions.
3. Backfill a sample tenant from existing event data; diff computed streaks against current SQL-derived values day-by-day.
4. Load test concurrent marking of the same subject-day and measure streak query latency at realistic row counts.
5. Wrap the package behind an internal ActivityService interface so product code never calls the vendor API directly.
6. Ship one low-risk feature, run parallel for a full streak cycle (≥30 days, ideally across a year boundary or DST change), then expand.
7. Define an exit path: if we keep raw events elsewhere, the wrapper lets us swap implementations without touching call sites.

Operational Impact

Maintenance

• Low code footprint but single-maintainer dependency — budget for periodic review of releases and a willingness to fork. Pin to ^1.0 and treat minor bumps as reviewable changes until the project demonstrates stability.
• The internal wrapper adds a small maintenance surface but is the cheapest insurance available here.

Support

• Documentation appears Chinese-first; confirm the team can consume it and that the issue tracker is responsive. If not, the wrapper plus our own internal docs (timezone convention, subject types, backfill runbook) become the real support material.

Scaling

• Storage is a non-issue: 46 bytes per subject-year, so 100k subjects × 5 years ≈ 23 MB — negligible.
• Read scaling is handled by the cache layer; ensure a shared cache and sane key-prefix namespacing per environment/tenant to avoid cross-environment collisions.
• Write scaling depends on contention on the per-subject-year row. Verify the concurrency protection under realistic parallel load; if it degrades to lock contention on hot subjects (e.g., a team-level subject with many writers), we may need to shard or queue marks.

Failure modes

• Cache staleness on transaction rollback (mitigated by after-commit invalidation — verify).
• Cache key collision across tenants/environments if the prefix is misconfigured.
• Day-boundary and DST drift producing "lost" or double-counted days for non-app-timezone users.
• Off-by-one at year boundaries and Feb 29 in streak math.
• Backfill on a subject that already has bitmap data — confirm idempotency and ordering guarantees.
• Loss of audit detail: if a support case needs "when exactly did this user check in," the bitmap cannot answer it.

Ramp-up

• The public API is small and self-explanatory (mark, backfill, calendar, counts, streaks); an engineer should be productive within a day. The byte-scan internals do not need to be understood to consume the API — but one person should own the streak-correctness validation and the timezone convention so it is not reinvented per team.
• Recommend a short internal write-up covering subject-type conventions, timezone policy, and the backfill runbook before the second team adopts it.