Architecture Decisions - RAISE Manifesto Website

Context

We want to maximize accessibility and encourage open feedback on the RAISE Manifesto, while keeping the site as simple as possible. Platforms like Reddit and Substack already offer robust, familiar commenting and discussion tools.

Decision

We will not build a native commenting system into the RAISE Manifesto site. Instead, we will share the site on platforms like Reddit and Substack, and direct visitors to join the discussion there. Links to these discussions will be included on the site.

Consequences

• The site remains extremely simple and easy to maintain.
• Readers can participate in discussion using platforms they already know.
• We lose some control over the discussion space, but gain reach and ease.
• If needs change, we can revisit the decision and add native comments later.

Context

We need a CSS architecture that is maintainable, provides visual consistency, and supports progressive enhancement while implementing our design system.

Decision

We will implement a CSS architecture with the following characteristics:

• CSS custom properties (variables) for design tokens
• Logical component-based organization
• No CSS preprocessors or frameworks
• Mobile-first responsive approach
• Progressive enhancement principles

Rationale

• Design System Implementation: CSS variables effectively implement our design tokens
• Maintainability: Component organization follows logical content structure
• Simplicity: Vanilla CSS3 provides the features we need without tooling complexity
• Accessibility: Mobile-first approach ensures content works on all devices
• Performance: No framework overhead means faster loading

Consequences

Positive:

• Straightforward architecture that's easy to understand
• No build step required for CSS processing
• Direct implementation of our design system
• Better performance through reduced file size

Negative:

• Limited code reuse mechanisms compared to preprocessors
• Some manual vendor prefixing may be needed for older browsers
• Potential for style inconsistencies without strict enforcement

Context

We need a hosting solution for the RAISE Manifesto website that is reliable, free or low-cost, and integrates well with our development workflow.

Decision

We will host the RAISE Manifesto website on GitHub Pages, using the organization's github.io domain.

Rationale

• Integration: Direct integration with our GitHub repository
• Cost: Free hosting for open source projects
• Reliability: GitHub's infrastructure provides excellent uptime
• Simplicity: Built-in deployment from repository branches
• Transparency: Open source hosting aligns with our values
• Community: Facilitates collaboration through GitHub's platform

Consequences

Positive:

• Automated deployment through git workflows
• Visibility of source code and development process
• No hosting costs
• Familiar platform for most developers

Negative:

• Limited to static content only
• No server-side processing capabilities
• Dependency on GitHub's platform and policies
• Limited performance optimization options