Skip to content

Commit a6587f6

Browse files
hyperpolymathclaude
hyperpolymath
and
claude
authored
Create roadmap and README documentation (#7)
- README.adoc: Document project vision, infrastructure status, technology stack, multi-forge distribution, and development setup - ROADMAP.adoc: Define 5-phase implementation plan from core library through advanced features, with current infrastructure checklist Project status: Infrastructure complete, implementation pending Co-authored-by: Claude <noreply@anthropic.com>
1 parent 53b9703 commit a6587f6

2 files changed

Lines changed: 361 additions & 2 deletions

File tree

‎README.adoc‎

Lines changed: 182 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,7 @@
11
= fireflag
22
Jonathan D.A. Jewell <jonathan.jewell@gmail.com>
33
:toc: macro
4+
:toclevels: 3
45
:icons: font
56
:source-highlighter: rouge
67
:experimental:
@@ -9,7 +10,186 @@ Jonathan D.A. Jewell <jonathan.jewell@gmail.com>
910
:url-bitbucket: https://bitbucket.org/hyperpolymath/fireflag
1011
:url-codeberg: https://codeberg.org/hyperpolymath/fireflag
1112

12-
Feature flag management with fire-and-forget semantics
13+
**Feature flag management with fire-and-forget semantics**
1314

1415
image:https://img.shields.io/badge/RSR-Certified-gold[RSR Certified,link=https://github.com/hyperpolymath/rhodium-standard-repositories]
15-
image:https://img.shields.io/badge/License-AGPL%20v3-blue[License]
16+
image:https://img.shields.io/badge/License-MIT%20OR%20AGPL--3.0-blue[License]
17+
image:https://img.shields.io/badge/Status-Infrastructure%20Ready-yellow[Status]
18+
19+
toc::[]
20+
21+
== Overview
22+
23+
fireflag is a feature flag management system designed around **fire-and-forget semantics** - set your flags and let the system handle propagation, caching, and consistency without manual intervention.
24+
25+
=== Current Project State
26+
27+
[IMPORTANT]
28+
====
29+
**Infrastructure Ready - Implementation Pending**
30+
31+
This repository contains comprehensive CI/CD infrastructure, policy enforcement, and multi-forge distribution. The actual feature flag implementation is the next phase of development. See link:ROADMAP.adoc[ROADMAP.adoc] for planned work.
32+
====
33+
34+
== Vision
35+
36+
fireflag aims to provide:
37+
38+
* **Fire-and-Forget Flag Management** - Configure once, propagate automatically
39+
* **Type-Safe SDK** - Built with ReScript for compile-time guarantees
40+
* **Edge-Ready** - Designed for distributed, low-latency evaluation
41+
* **Self-Hostable** - Full control over your feature flag infrastructure
42+
* **FOSS-First** - No vendor lock-in, dual-licensed MIT/AGPL-3.0
43+
44+
== Repository Infrastructure
45+
46+
The repository is production-ready with comprehensive infrastructure:
47+
48+
=== CI/CD Workflows (12 Active)
49+
50+
[cols="1,2",options="header"]
51+
|===
52+
|Workflow |Purpose
53+
54+
|`rsr-antipattern.yml`
55+
|Enforces language policy (blocks TypeScript, Go, non-SaltStack Python)
56+
57+
|`npm-bun-blocker.yml`
58+
|Blocks npm/bun artifacts in favor of Deno
59+
60+
|`guix-nix-policy.yml`
61+
|Enforces Guix (primary) / Nix (fallback) package management
62+
63+
|`security-policy.yml`
64+
|Blocks weak crypto, HTTP URLs, hardcoded secrets
65+
66+
|`wellknown-enforcement.yml`
67+
|RFC 9116 security.txt validation
68+
69+
|`workflow-linter.yml`
70+
|Validates SPDX headers, SHA-pinned actions, permissions
71+
72+
|`instant-sync.yml`
73+
|Triggers forge propagation on push/release
74+
75+
|`mirror.yml`
76+
|Syncs to GitLab and Bitbucket mirrors
77+
78+
|`quality.yml`
79+
|File permissions, secrets scanning, TODO tracking, EditorConfig
80+
81+
|`jekyll-gh-pages.yml`
82+
|Documentation site deployment
83+
84+
|`codeql.yml`
85+
|Security analysis (activates with source code)
86+
87+
|`scorecard.yml`
88+
|OSSF security scorecard
89+
|===
90+
91+
=== Multi-Forge Distribution
92+
93+
fireflag is mirrored across multiple forges for resilience:
94+
95+
[horizontal]
96+
GitHub (Primary):: {url-github}
97+
GitLab:: {url-gitlab}
98+
Bitbucket:: {url-bitbucket}
99+
Codeberg:: {url-codeberg}
100+
101+
Automatic synchronization keeps all mirrors current via `instant-sync.yml`.
102+
103+
== Technology Stack
104+
105+
fireflag follows the Hyperpolymath Language Policy:
106+
107+
=== Approved Stack
108+
109+
[cols="1,2",options="header"]
110+
|===
111+
|Technology |Use Case
112+
113+
|**ReScript**
114+
|Primary application code (type-safe, compiles to JS)
115+
116+
|**Rust**
117+
|Performance-critical components, CLI tools, WASM
118+
119+
|**Deno**
120+
|Runtime and package management (replaces Node/npm)
121+
122+
|**Gleam**
123+
|Backend services (BEAM or JS target)
124+
125+
|**Tauri 2.0+ / Dioxus**
126+
|Mobile applications (Rust-first approach)
127+
128+
|**Bash/POSIX**
129+
|Build scripts and automation (minimal)
130+
|===
131+
132+
=== Explicitly Banned
133+
134+
TypeScript, Node.js, npm, Bun, Go, general Python, Java, Kotlin, Swift, React Native, Flutter
135+
136+
See link:.claude/CLAUDE.md[.claude/CLAUDE.md] for full language policy.
137+
138+
== Development
139+
140+
=== Prerequisites
141+
142+
* https://deno.land/[Deno] (runtime)
143+
* https://github.com/casey/just[just] (task runner)
144+
* https://guix.gnu.org/[GNU Guix] or https://nixos.org/[Nix] (package management)
145+
146+
=== Task Runner
147+
148+
[source,bash]
149+
----
150+
# List available tasks
151+
just
152+
153+
# Build (when implemented)
154+
just build
155+
156+
# Test (when implemented)
157+
just test
158+
159+
# Format code
160+
just fmt
161+
162+
# Lint code
163+
just lint
164+
----
165+
166+
== License
167+
168+
Dual-licensed under your choice of:
169+
170+
* **MIT License** - Maximum flexibility for most uses
171+
* **AGPL-3.0-or-later** - Copyleft protection for network services
172+
173+
Additionally encourages (non-binding) adherence to https://github.com/hyperpolymath/palimpsest-license[Palimpsest License] principles around consent-based digital interaction.
174+
175+
See link:LICENSE.txt[LICENSE.txt] for full terms.
176+
177+
== Contributing
178+
179+
Contributions welcome! Please ensure:
180+
181+
* Code follows the approved technology stack
182+
* All CI checks pass
183+
* SPDX license headers on new files
184+
* SHA-pinned dependencies
185+
186+
== Citation
187+
188+
See link:docs/CITATIONS.adoc[docs/CITATIONS.adoc] for citation formats (BibTeX, APA, MLA, Harvard, OSCOLA).
189+
190+
== Links
191+
192+
* link:ROADMAP.adoc[Development Roadmap]
193+
* link:docs/CITATIONS.adoc[Citation Guide]
194+
* link:.claude/CLAUDE.md[Language Policy]
195+
* https://github.com/hyperpolymath/rhodium-standard-repositories[RSR Framework]

‎ROADMAP.adoc‎

Lines changed: 179 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,179 @@
1+
= fireflag Roadmap
2+
:toc: macro
3+
:toclevels: 2
4+
:icons: font
5+
6+
Development roadmap for fireflag - feature flag management with fire-and-forget semantics.
7+
8+
toc::[]
9+
10+
== Current Status
11+
12+
[cols="1,3",options="header"]
13+
|===
14+
|Component |Status
15+
16+
|**Repository Infrastructure**
17+
|Complete - CI/CD, multi-forge mirroring, policy enforcement
18+
19+
|**Language Policy**
20+
|Complete - ReScript/Rust/Deno stack defined and enforced
21+
22+
|**Core Implementation**
23+
|Not Started - Pending
24+
25+
|**SDK**
26+
|Not Started - Pending
27+
28+
|**Documentation**
29+
|Partial - README and ROADMAP complete, API docs pending
30+
|===
31+
32+
== Phase 1: Core Library
33+
34+
=== 1.1 Data Model (ReScript)
35+
36+
* [ ] Flag type definitions
37+
** Boolean flags
38+
** String/enum variants
39+
** Percentage rollouts
40+
** User segment targeting
41+
* [ ] Targeting rules schema
42+
* [ ] Evaluation context types
43+
* [ ] Flag state serialization
44+
45+
=== 1.2 Evaluation Engine (Rust/WASM)
46+
47+
* [ ] High-performance flag evaluator
48+
* [ ] Targeting rule matcher
49+
* [ ] Percentage bucketing (deterministic hashing)
50+
* [ ] WASM compilation for edge deployment
51+
* [ ] ReScript bindings
52+
53+
=== 1.3 Storage Adapters
54+
55+
* [ ] In-memory store (default)
56+
* [ ] File-based persistence (JSON/TOML)
57+
* [ ] SQLite adapter
58+
* [ ] Redis adapter (optional)
59+
60+
== Phase 2: Fire-and-Forget Runtime
61+
62+
=== 2.1 Background Sync
63+
64+
* [ ] Change detection and propagation
65+
* [ ] Conflict resolution strategy
66+
* [ ] Retry with exponential backoff
67+
* [ ] Offline queue and replay
68+
69+
=== 2.2 Caching Layer
70+
71+
* [ ] Multi-tier cache (memory -> disk -> remote)
72+
* [ ] TTL and invalidation
73+
* [ ] Stale-while-revalidate semantics
74+
* [ ] Cache warming on startup
75+
76+
=== 2.3 Event System
77+
78+
* [ ] Flag change events
79+
* [ ] Evaluation events (for analytics)
80+
* [ ] Audit logging
81+
* [ ] Webhook dispatch
82+
83+
== Phase 3: SDK & Integrations
84+
85+
=== 3.1 Server SDK (Gleam)
86+
87+
* [ ] BEAM/Erlang runtime integration
88+
* [ ] Process-based flag caching
89+
* [ ] Hot flag updates without restart
90+
* [ ] Telemetry integration
91+
92+
=== 3.2 Client SDK (ReScript)
93+
94+
* [ ] Browser runtime
95+
* [ ] React/Dioxus hooks
96+
* [ ] Local evaluation mode
97+
* [ ] Streaming updates (SSE)
98+
99+
=== 3.3 CLI (Rust)
100+
101+
* [ ] `fireflag init` - Project setup
102+
* [ ] `fireflag set` - Set flag values
103+
* [ ] `fireflag get` - Query flag state
104+
* [ ] `fireflag sync` - Force synchronization
105+
* [ ] `fireflag export/import` - Bulk operations
106+
107+
== Phase 4: Management Interface
108+
109+
=== 4.1 Admin API (Gleam)
110+
111+
* [ ] REST API for flag management
112+
* [ ] GraphQL API (optional)
113+
* [ ] Authentication/authorization
114+
* [ ] Multi-environment support
115+
116+
=== 4.2 Web Dashboard (ReScript + Tauri)
117+
118+
* [ ] Flag listing and search
119+
* [ ] Flag editor with validation
120+
* [ ] Targeting rule builder
121+
* [ ] Audit log viewer
122+
* [ ] Environment switcher
123+
124+
== Phase 5: Advanced Features
125+
126+
=== 5.1 Experimentation
127+
128+
* [ ] A/B testing framework
129+
* [ ] Metric collection
130+
* [ ] Statistical analysis
131+
* [ ] Experiment scheduling
132+
133+
=== 5.2 Governance
134+
135+
* [ ] Change approval workflows
136+
* [ ] Scheduled flag changes
137+
* [ ] Flag lifecycle management
138+
* [ ] Stale flag detection
139+
140+
=== 5.3 Observability
141+
142+
* [ ] OpenTelemetry integration
143+
* [ ] Prometheus metrics
144+
* [ ] Distributed tracing
145+
* [ ] Performance dashboards
146+
147+
== Infrastructure Complete
148+
149+
The following infrastructure is already in place:
150+
151+
=== CI/CD Workflows
152+
153+
* [x] Language policy enforcement (TypeScript, Go, npm blocked)
154+
* [x] Security policy (no weak crypto, HTTPS only, no secrets)
155+
* [x] Multi-forge mirroring (GitHub, GitLab, Bitbucket, Codeberg)
156+
* [x] Instant sync on push/release
157+
* [x] OSSF Scorecard integration
158+
* [x] CodeQL ready (activates with source code)
159+
* [x] EditorConfig compliance
160+
* [x] SPDX header validation
161+
* [x] SHA-pinned dependencies enforcement
162+
163+
=== Repository Standards
164+
165+
* [x] Dual MIT/AGPL-3.0 licensing
166+
* [x] RSR (Rhodium Standard Repository) certification
167+
* [x] Citation documentation (BibTeX, APA, MLA, Harvard, OSCOLA)
168+
* [x] Development task runner (justfile)
169+
* [x] Palimpsest License principles (non-binding overlay)
170+
171+
== Contributing
172+
173+
Contributions to any phase are welcome. Priority areas:
174+
175+
1. **Phase 1.1** - Data model design and ReScript types
176+
2. **Phase 1.2** - Rust evaluation engine architecture
177+
3. **Phase 2.1** - Fire-and-forget sync protocol design
178+
179+
See link:README.adoc[README.adoc] for development setup and contribution guidelines.

0 commit comments

Comments
 (0)