Core First Architecture
PayCal Core contains the canonical domain and controller logic: calculations, validation, permissions, lifecycle policy, and shared API contracts.
Core remains extension-agnostic by design. Integration points are isolated through bridge contracts so core services can be tested independently of runtime-specific packages.
Basic Extensions Included In This Repository
This repository ships basic extension implementations that provide default behavior for extension seams. These act as public reference packages and safe defaults for self-hosted deployments.
- billing-provider: baseline billing capability hooks and mode selection
- earnings-ytd: baseline YTD rendering and earnings hook points
- organization-signals: baseline organization signal hooks
Third-Party Extension Model
Third parties using this repository can create and maintain their own extension packages. The expected model is:
- Keep core logic unmodified whenever possible
- Implement custom behavior in extension packages
- Bind custom packages through documented extension bootstrap and hook seams
- Preserve core contracts so upstream upgrades remain manageable
This allows competitive and vertical-specific deployments without forcing long-term forks of core domain code.
Canonical paycal.app Differentiation
The canonical https://paycal.app platform runs private extension variants on top of the same core and basic extension paradigm.
These private variants are a deliberate product differentiation layer for PayCal-operated environments. They can tune workflows, capability behavior, and UI-specific integrations while preserving compatibility with the same core architecture.
- Core logic remains shared and auditable
- Public/basic extensions remain available in-repo
- Private extensions provide canonical platform differentiation
Transparency Commitments
- Core contracts are documented and tested at extension seams
- Bridge boundaries are explicit to make coupling discoverable
- Extension behavior can evolve without destabilizing core services
- Self-hosted adopters are free to build alternative extension strategies