Design modular Slugkit package architecture #228

New issue

Closed

opened 2026-06-28 15:09:03 -05:00 by erik · 3 comments

erik commented

2026-06-28 15:09:03 -05:00

Owner

Goal

Create a design and architecture proposal for extracting reusable Slugkit libraries/packages under the @evcraddock/slug-* npm namespace so generated websites can receive shared improvements while staying independently owned and customizable.

Requirements

Define proposed package boundaries, including at minimum @evcraddock/slug-core, @evcraddock/slug-api, @evcraddock/slug-auth, @evcraddock/slug-media, @evcraddock/slug-federation, @evcraddock/slug-template, and the existing @evcraddock/slug-cli.
Describe responsibilities, public API expectations, dependencies, and non-goals for each package.
Recommend an incremental extraction sequence that allows implementing one package at a time without breaking the current template site or CLI.
Explain how generated websites should consume packages while preserving local customization and escape hatches.
Cover versioning, compatibility, upgrade, and publishing considerations for generated sites.
Identify risks and tradeoffs, especially around over-abstraction, database ownership, auth/security updates, federation complexity, and package scope migration.
Update or add project documentation with the proposal.

Acceptance criteria

A documented architecture/design proposal exists in the repository.
The proposal uses the @evcraddock/slug-* package naming strategy.
The proposal includes a package dependency graph or equivalent dependency-direction explanation.
The proposal defines an incremental, one-package-at-a-time implementation plan.
The proposal describes how generated sites can receive package updates without losing ownership/customization.
The proposal identifies follow-up implementation tasks or phases.

Dependencies

None

## Goal Create a design and architecture proposal for extracting reusable Slugkit libraries/packages under the `@evcraddock/slug-*` npm namespace so generated websites can receive shared improvements while staying independently owned and customizable. ## Requirements - Define proposed package boundaries, including at minimum `@evcraddock/slug-core`, `@evcraddock/slug-api`, `@evcraddock/slug-auth`, `@evcraddock/slug-media`, `@evcraddock/slug-federation`, `@evcraddock/slug-template`, and the existing `@evcraddock/slug-cli`. - Describe responsibilities, public API expectations, dependencies, and non-goals for each package. - Recommend an incremental extraction sequence that allows implementing one package at a time without breaking the current template site or CLI. - Explain how generated websites should consume packages while preserving local customization and escape hatches. - Cover versioning, compatibility, upgrade, and publishing considerations for generated sites. - Identify risks and tradeoffs, especially around over-abstraction, database ownership, auth/security updates, federation complexity, and package scope migration. - Update or add project documentation with the proposal. ## Acceptance criteria - [ ] A documented architecture/design proposal exists in the repository. - [ ] The proposal uses the `@evcraddock/slug-*` package naming strategy. - [ ] The proposal includes a package dependency graph or equivalent dependency-direction explanation. - [ ] The proposal defines an incremental, one-package-at-a-time implementation plan. - [ ] The proposal describes how generated sites can receive package updates without losing ownership/customization. - [ ] The proposal identifies follow-up implementation tasks or phases. ## Dependencies - None

erik added the

labels

2026-06-28 15:09:03 -05:00

erik commented

2026-06-28 16:39:07 -05:00

Author

Owner

Synced from todu comment by @todu on 2026-06-28T21:36:41.365Z

Review update

PR: #229 is open with CI passing.
Result: approved.
Follow-up: waiting for explicit human merge approval.

_Synced from todu comment by @todu on 2026-06-28T21:36:41.365Z_ ### Review update - PR: #229 is open with CI passing. - Result: approved. - Follow-up: waiting for explicit human merge approval.

erik commented

2026-06-28 22:27:30 -05:00

Author

Owner

Synced from todu comment by @todu on 2026-06-29T03:27:18.367Z

Review update

PR: #229 updated with docs/npm-specs/ implementation-unit specs.
Result: approved after update.
Verified: ./scripts/pre-pr.sh passed and Forgejo CI build-lint-test passed for a368519.
Follow-up: waiting for explicit human merge approval.

_Synced from todu comment by @todu on 2026-06-29T03:27:18.367Z_ ### Review update - PR: #229 updated with `docs/npm-specs/` implementation-unit specs. - Result: approved after update. - Verified: `./scripts/pre-pr.sh` passed and Forgejo CI `build-lint-test` passed for `a368519`. - Follow-up: waiting for explicit human merge approval.

erik

2026-06-28 22:33:10 -05:00

closed this issue
added
status:done
and removed
status:inprogress
labels

erik commented

2026-06-28 22:33:12 -05:00

Author

Owner

Synced from todu comment by @todu on 2026-06-29T03:31:19.994Z

Completed

Implemented package architecture documentation in docs/package-architecture.md.
Added implementation-unit specs in docs/npm-specs/ covering workspace scaffolding, package extraction, template consumption, generated-site dependency behavior, npm publishing/deployment, and diagnostics.
Created follow-up implementation tasks in dependency order for the npm package work.
Verified PR #229 was reviewed, CI passed, and the PR was merged into main.

_Synced from todu comment by @todu on 2026-06-29T03:31:19.994Z_ ### Completed - Implemented package architecture documentation in `docs/package-architecture.md`. - Added implementation-unit specs in `docs/npm-specs/` covering workspace scaffolding, package extraction, template consumption, generated-site dependency behavior, npm publishing/deployment, and diagnostics. - Created follow-up implementation tasks in dependency order for the npm package work. - Verified PR #229 was reviewed, CI passed, and the PR was merged into `main`.