CepatEdge

Appearance

OSS Launch & Public Repo Plan for CepatEdge ​

Status: Draft → Ready for Execution
Target Repo: https://github.com/zamdevio/cepat-edge
License: MIT
Goal: Make the repo professional, instantly deployable, community-friendly, and flexible for real-world chaos while keeping the original university handover spirit alive.

Summary: This plan turns CepatEdge from a solo university project into a world-class open-source CMMS in one focused sprint.

1. License Decision & Legal Setup ​

Why MIT Instead of AGPL ​

We chose MIT to maximise adoption and trust while keeping the project clearly attributed and open for commercial use. Below is a focused comparison.

CriterionMITAGPL
Adoption✅ Very high; companies can use without legal review⚠️ Often blocked by legal; “viral” clause causes friction
Protection❌ No copyleft; derivatives can be closed-source✅ Network-use trigger; SaaS must share modifications
Commercial use✅ Explicitly allowed; no obligations⚠️ Allowed but with share-alike for modified versions
Enterprise fit✅ Easy to adopt for universities & SMEs⚠️ Requires legal sign-off in many orgs
Community✅ Low barrier; more forks, stars, contributors⚠️ Smaller pool of adopters who accept copyleft
Our goal✅ “Use it, deploy it, fork it, sell support”❌ Better if we wanted to force all forks to stay open

Conclusion: For a CMMS we want in the hands of as many organisations as possible—especially cost-sensitive universities and SMEs—MIT is the right choice. We prioritise adoption and real-world use over legal protection of derivatives. Commercial support and hosted offerings can be built on top without license friction.

Top-Level NOTICE File ​

Create NOTICE in the repo root with this exact line:

Built by @zamdevio – happy to discuss commercial use, support, or custom deployments.

CONTRIBUTING.md ​

Create CONTRIBUTING.md in the repo root. It must include:

  • Statement: “Built by @zamdevio – happy to discuss commercial use/support.”
  • Full contribution guidelines:
    • How to report bugs (use GitHub Issues, include version and steps).
    • How to propose features (Issue or Discussion first, then PR if agreed).
    • Code standards (TypeScript, lint, tests).
    • PR process (target branch, description template, review expectations).
    • License: contributions accepted under MIT; you retain copyright, we get a license to use.
    • Where to ask questions (Issues, Discussions, or contact for commercial/support).

(The actual full text of CONTRIBUTING.md will be generated in the “Repo Setup” section below.)

2. Repo Structure & Cleanup for Public Eyes ​

Redesign docs/ to be public-first: clear, professional, and welcoming to external readers.

2.1 Rename and Refocus: institutional-readiness/ → institutions/ ​

ActionDetail
Renamedocs/institutional-readiness/ → docs/institutions/
KeepOnly clean, general-purpose files (no institution-specific names or internal jargon).
RemovePilot-specific checklists, RACI with real names, or anything that reads “internal only.”

2.2 New Content in docs/institutions/ ​

Create fresh, clear docs under docs/institutions/ that answer “What Organizations Care About Most”:

DocPurpose
README.mdIndex: what this section is for and links to each doc.
cost-and-licensing.mdTotal cost of ownership, free tier, scaling costs, zero-license advantage.
security-and-compliance.mdSecurity posture, audit logging, data handling, compliance considerations.
deployment-and-ops.mdDeployment options (self-host, Cloudflare, other), maintenance, upgrades.
maintenance-and-support.mdHow to maintain the system, where to get help, support options.
compliance-and-governance.mdData retention, access control, governance (generic, not institution-specific).

Tone: confident, factual, no hype. Speak to a cautious IT or security officer.

2.3 docs/todo/ → Single Source of Truth for “Planned After Launch” ​

ActionDetail
DeleteEvery file in docs/todo/ except those that are clearly “future roadmap” / “planned changes after public launch.”
KeepOne consolidated roadmap (e.g. roadmap.md or merge into existing docs/strategy/roadmap.md and keep a short docs/todo/README.md that points there + lists “Planned changes after public launch” with checklists).
Resultdocs/todo/ is the single place contributors look to see what’s coming next.

Suggested cleanup:

  • Delete from docs/todo/: technical-debt.md, user-documentation.md, failure-tests-plan.md, architectural-weak-points.md, next-session-maintenance-stabilization.md, improvements.md, api-documentation.md, r2-manual-versioning-plan.md, tests/README.md (or move to docs/guides/ if still relevant).
  • Keep / create: docs/todo/README.md (explains “this folder = planned work post-launch”) and either docs/todo/roadmap.md or a single ROADMAP.md that links to docs/strategy/roadmap.md and adds “Post–public launch” items.

2.4 Other Doc Folders (Keep and Polish) ​

FolderAction
docs/architecture/Keep. Ensure ADRs and diagrams are beginner-friendly; add one-line “Why this matters” where useful.
docs/guides/Keep. Polish getting-started, deployment, API; ensure no internal-only steps.
docs/security/Keep. Ensure overview and data-retention docs are public-safe and clear.
docs/strategy/Keep. Remove or generalize any institution-specific strategy; keep vision and roadmap.
docs/workflows/Keep. Development and deployment workflows; remove internal-only references.

2.5 New Top-Level Files ​

FilePurpose
SECURITY.mdHow to report vulnerabilities (e.g. private email or GitHub Security Advisories); no public disclosure before fix.
CODE_OF_CONDUCT.mdContributor behaviour (e.g. Contributor Covenant); link from README and CONTRIBUTING.
SUPPORT.mdWhere to get help: community (Issues/Discussions), docs, and “for commercial support or custom deployments, contact @zamdevio.”

3. Repo Setup (Make It Undeniable) ​

3.1 Repository Name ​

3.2 README.md (Exact Content to Generate) ​

Structure (generate full text from this spec):

  1. Hero

    • Project name: CepatEdge
    • One-line tagline: e.g. “Edge-native CMMS — fast, cheap, open.”
    • Short paragraph: maintenance management on the edge; global speed; minimal cost; MIT.

  2. Screenshot / visual

    • Placeholder: “Screenshot or demo GIF here” with a clear <!-- TODO: add screenshot --> or image link.

  3. Tech stack table

    LayerTech
    RuntimeCloudflare Workers
    APIHono
    DatabaseNeon PostgreSQL + Drizzle
    CacheDurable Objects
    FrontendReact (SPA)
    HostingCloudflare Pages
    StorageCloudflare R2

  4. Badges

    • License: MIT
    • Cloudflare Workers
    • TypeScript
    • Drizzle
    • Optional: build status (e.g. GitHub Actions), npm/version if applicable.

  5. One-click / quick deploy

    • “Deploy to Cloudflare” or “Quick start” that points to DEPLOY.md and/or docs/guides/getting-started.md.

  6. Origin note

    • “Originally built and proposed to UCSI University. Now open for the world.”

  7. Links

    • Docs, Contributing, Security, Support, License.

3.3 .github/ Folder Structure ​

Create:

.github/
  ISSUE_TEMPLATE/
    bug_report.md
    feature_request.md
    config.yml          (optional: issue template chooser)
  PULL_REQUEST_TEMPLATE.md
  workflows/
    ci.yml              (lint + typecheck + test on PR/push)
  • Issue templates: Bug (steps, env, version), Feature (use case, acceptance criteria).
  • PR template: What changed, how to test, checklist (lint, tests, docs if needed).
  • CI workflow: Run on main and PRs: pnpm install, pnpm lint, pnpm type-check, pnpm test (or per-app if monorepo). Fail fast so the repo looks maintained.

4. Make Deployment Stupidly Easy ​

4.1 Seed Script Upgrade (apps/worker/scripts/) ​

Upgrade the existing seed script to be much more advanced:

RequirementImplementation
Interactive CLIPrompts for env (local/staging/prod), confirmations, and optional demo data.
Environment detectionDetect NODE_ENV / DATABASE_URL and warn if pointing at prod.
Safe defaultsNo destructive ops without explicit --reset and confirmation.
One-command prod seede.g. pnpm seed:prod that runs with production checks and prompts for admin email/password.
Automatic admin creationPrompt for admin email + password (with strength check); create first super_admin.
Clear success messages“Admin created: …”, “Demo data: yes/no”, “Next: run migrations / deploy.”

Suggested script surface:

  • pnpm db:seed — interactive (current behaviour, improved).
  • pnpm seed:prod — production-safe: env check, single admin creation, no demo data unless flag.
  • pnpm db:seed-demo — add demo data (keep existing behaviour).

4.2 New Root DEPLOY.md ​

Create DEPLOY.md at repo root with zero-to-deploy steps:

  1. Prerequisites: Node 18+, pnpm, Cloudflare account, Neon (or Postgres) account.
  2. Clone and install: git clone …, pnpm install.
  3. Environment: Copy .env.example to .env; fill every variable (with short comments).
  4. Database: Create DB, run migrations (pnpm db:push), run seed (pnpm db:seed or pnpm seed:prod).
  5. Workers: Configure wrangler.jsonc (or env), then pnpm deploy in apps/worker.
  6. Pages: Configure and deploy frontend from apps/web (and optionally apps/docs).
  7. Verify: Health check URL, first login, create a maintenance request.

Target: a non-technical maintainer can follow and deploy in <10 minutes with copy-paste.

4.3 Example Environment and Wrangler ​

  • .env.example (root or per-app as needed): List every required variable with a one-line comment (e.g. DATABASE_URL, JWT_SECRET, RESEND_API_KEY, Cloudflare account id, etc.). No real secrets.
  • wrangler.jsonc: Add short comments for each binding and var (e.g. “Replace with your Neon connection string”, “Set via secret in prod”). Add or reference a “Deployment” section in README or DEPLOY.md that points to this file and deployment scripts.

5. Push & Promote Strategy ​

5.1 Launch Checklist (Timing) ​

StepWhenAction
1Day 0–1Repo cleanup, docs reorg, NOTICE/CONTRIBUTING/SECURITY/COC/SUPPORT.
2Day 2README, badges, DEPLOY.md, seed script upgrade, .github templates and CI.
3Day 3Final pass: links, license, remove internal references.
4Day 4Push to public zamdevio/cepat-edge; ensure default branch and protection.
5Day 5Tweet thread (see below); same day or next: LinkedIn post.
6Day 5–6Share in communities (see below).
7Day 7Post-launch: triage issues, thank first contributors, update SUPPORT/README if needed.

5.2 Ready-to-Post X (Twitter) Thread (3–4 Tweets) ​

Tweet 1:
We just open-sourced CepatEdge — an edge-native CMMS (maintenance management) built on @Cloudflare Workers, Drizzle, and React. Sub-100ms globally, minimal cost, MIT. Originally built for a university; now for everyone. 🧵

Tweet 2:
What you get: role-based workflows (Staff → HOD → Technician), JWT auth, audit logs, file storage on R2, and a single-command deploy. No vendor lock-in on the DB (Postgres) or storage (S3-compatible). Perfect for schools, facilities, and small teams.

Tweet 3:
Repo: github.com/zamdevio/cepat-edge — clone, set env, run seed, deploy. Docs and DEPLOY.md get you live in minutes. Built by @zamdevio. Happy to discuss commercial use, support, or custom deployments.

Tweet 4 (optional):
If you’re into edge runtimes, CMMS, or just want to see a real Workers + Durable Objects + Neon stack in action, give it a star or open an issue. We’d love feedback from the community.

5.3 LinkedIn Post (Short Version) ​

  • Title: “Open-sourcing CepatEdge: Edge-native maintenance management.”
  • Body: 2–3 sentences on what it is (CMMS on Cloudflare Workers, fast, low cost, MIT), who it’s for (universities, facilities, SMEs), and that it started as a university project and is now public. Link to repo and “happy to discuss commercial use or support.” Professional, no hype.

5.4 Places to Share ​

  • Malaysian dev communities: e.g. Facebook groups (Malaysian Developers), Telegram/Discord dev groups, MY dev forums.
  • Reddit: r/opensource, r/selfhosted, r/malaysia (if relevant), r/cloudflare (if exists), r/sysadmin (short, factual post).
  • Cloudflare: Discord (e.g. #workers, #showcase), Community forum, DevRel if you have a contact.
  • Other: HN “Show HN” (when ready for a bit of traffic), Dev.to or Medium post that links to repo and DEPLOY.md.

5.5 Hashtags and Tagging ​

  • Hashtags: #OpenSource #CMMS #CloudflareWorkers #EdgeComputing #MaintenanceManagement #MITLicense
  • Tag: @CloudflareDevs (and @Cloudflare if appropriate) in the Twitter thread.
  • Mention: “Built by @zamdevio” in repo and posts.

5.6 Post-Launch Engagement ​

  • Issues: Triage within 1–2 days; label (bug/feature/docs), thank reporter, set expectations (e.g. “we’ll look at this by X”).
  • PRs: Review within a few days; merge or request changes; thank contributor in release notes or README.
  • Feature requests: Track in Issues or docs/todo/; say “we’re considering this” or “added to roadmap.”
  • Releases: Tag versions (e.g. v1.0.0 at launch); maintain a simple CHANGELOG so adopters can follow.

6. Flexibility for Real-World Chaos ​

6.1 Multi-Tenant Readiness Roadmap ​

  • Current: Single-tenant; one org per deployment.
  • Later: Document a “Multi-tenant roadmap” in docs/architecture/ or docs/todo/: org id on key tables, tenant-aware auth, optional tenant-specific R2 prefix or bucket, feature flags per tenant. No commitment to timeline; show we’ve thought about it so enterprises can plan.

6.2 Configuration System ​

  • Env vars: Central list in .env.example and DEPLOY.md; document which are required vs optional.
  • System settings table: Document in docs/guides/configuration/ (or equivalent): what is configurable at runtime (e.g. branding, limits, feature flags) and how to change it. Plan for future: more settings in DB, optional admin UI.

6.3 Error Handling and Logging (Production) ​

  • Strategy doc: Short docs/architecture/error-handling-and-logging.md (or under docs/guides/): how errors are returned (format, codes), what is logged (no secrets), and where (Workers logs, optional external). Recommend structured logs and a small set of error codes for clients.
  • Implementation: Ensure API errors are consistent (e.g. 4xx/5xx, JSON body); log with request id or correlation id where possible.

6.4 Versioning and Migrations ​

  • DB schema: Use Drizzle migrations; store in repo; document in DEPLOY.md (“run migrations before seed”). Plan: semantic versioning for API (e.g. v1 in path or header) and for DB (migration numbering).
  • Releases: Tag releases (e.g. v1.0.0); CHANGELOG for breaking changes and migration steps so deployers can upgrade safely.

6.5 Community Governance ​

  • Who can merge: Document in CONTRIBUTING: maintainers (@zamdevio or listed in README) merge after review; no direct push to main from external.
  • Release process: Tag from main after tests pass; optionally GitHub Actions to build and attach artifacts; release notes from CHANGELOG. Keep it simple at first.

6.6 Future Monetization (Without Breaking OSS) ​

  • Dual-license: Stay MIT-only for now; if ever needed, consider offering a commercial license for those who want to use without open-sourcing their fork (only if we add substantial proprietary value).
  • Hosted / sponsored version: Offer “CepatEdge Cloud” or “managed CepatEdge” as a paid service; repo stays MIT so self-host remains possible.
  • Support and custom work: “Built by @zamdevio – happy to discuss commercial use, support, or custom deployments” in NOTICE and SUPPORT; link to a simple contact (email or form). No paywall on the code.

7. Timeline & Checklist ​

  • [ ] Add root LICENSE (MIT).
  • [ ] Add root NOTICE (exact line: “Built by @zamdevio – happy to discuss commercial use, support, or custom deployments.”).
  • [ ] Create CONTRIBUTING.md (statement + full guidelines).
  • [ ] Rename docs/institutional-readiness/ → docs/institutions/; remove institution-specific content.
  • [ ] Delete non-roadmap files from docs/todo/; turn docs/todo/ into “Planned changes after public launch” only.
  • [ ] Add SECURITY.md, CODE_OF_CONDUCT.md, SUPPORT.md.

Day 1: Seed Script and Deploy Docs ​

  • [ ] Upgrade seed script: interactive CLI, env detection, pnpm seed:prod, admin prompts, clear messages.
  • [ ] Add DEPLOY.md at root (zero-to-deploy, <10 min).
  • [ ] Add or update .env.example with every variable documented.
  • [ ] Add comments to wrangler.jsonc and reference in DEPLOY.md.

Day 2: README and Repo Polish ​

  • [ ] Rewrite README.md: hero, screenshot placeholder, tech stack table, badges, one-click deploy, “Originally built & proposed to UCSI University.”
  • [ ] Create .github/ISSUE_TEMPLATE/ (bug, feature).
  • [ ] Create .github/PULL_REQUEST_TEMPLATE.md.
  • [ ] Add .github/workflows/ci.yml (lint, typecheck, test).

Day 3: Docs and Institutions ​

  • [ ] Create docs/institutions/ content: cost, security, deployment, maintenance, compliance, zero-license.
  • [ ] Polish docs/architecture/, docs/guides/, docs/security/, docs/strategy/, docs/workflows/ for public.
  • [ ] Final link check and internal-reference pass.

Day 4: Repo Go-Live ​

  • [ ] Create or make public zamdevio/cepat-edge; set default branch.
  • [ ] Push all changes; ensure CI is green.
  • [ ] Branch protection: require PR reviews and CI for main (optional but recommended).
  • [ ] Verify README, DEPLOY.md, and badges render correctly.

Day 5: First Promotion ​

  • [ ] Post X thread (3–4 tweets as above).
  • [ ] Post LinkedIn post.
  • [ ] Share in 1–2 chosen communities (e.g. Cloudflare Discord, Reddit).

Day 6: Broaden Reach ​

  • [ ] Share in remaining communities (Malaysian dev, r/opensource, r/selfhosted, etc.).
  • [ ] Pin repo “About” and description; add topics (e.g. cmms, cloudflare-workers, drizzle, open-source).

Day 7: Post-Launch ​

  • [ ] Triage new issues; label and respond.
  • [ ] Thank first contributors or stars in a short follow-up post or README.
  • [ ] Update SUPPORT.md or README if questions show gaps.
  • [ ] Optional: tag v1.0.0 and add first CHANGELOG entry.

This document is the single execution plan for the OSS launch. Update status to “Ready for Execution” when the team approves, then work through the 7-day checklist.