Skip to content

Feature/vibes docs#181

Open
jermbo wants to merge 26 commits into
mainfrom
feature/vibes-docs
Open

Feature/vibes docs#181
jermbo wants to merge 26 commits into
mainfrom
feature/vibes-docs

Conversation

@jermbo

@jermbo jermbo commented Jul 10, 2026

Copy link
Copy Markdown
Owner

SampleAPIs 3.0 — Modernization, Playground, and Documentation

Summary

This is a major 3.0.0 release that modernizes the client and server, replaces the old json-server/GraphQL stack with an owned REST router, adds an in-browser CodeMirror Playground, and introduces a full project wiki under docs/.

Client

  • Migrates routing to TanStack Router and data fetching to TanStack Query (drops custom useFetch / useLocalStorage hooks)
  • Replaces SCSS with plain CSS + design tokens; adds self-hosted fonts via @fontsource
  • Adds a new Playground: CodeMirror 6 editor, sandboxed iframe runner, JSON tree output, per-endpoint localStorage persistence, and starter snippets
  • Removes CodepenWrapper and legacy generate-react-cli scaffolding
  • Swaps ESLint → OXLint

Server

  • Replaces json-server with a ~240-line custom jsonRouter (json-server-compatible CRUD, async disk I/O, per-file write locking)
  • Removes GraphQL entirely (GraphQL_Basics.md, client images, server routes/tests)
  • Upgrades to Express 5, bumps dependencies, adds /health endpoint
  • Removes deprecated APIs: bitcoin, rickandmorty
  • Updates coffee dataset (English copy, expanded endpoints) and refreshes several other JSON files
  • Drops custom-apis route and generated API list plumbing

Documentation & ops

  • Adds a structured wiki in docs/ (architecture, API surface, data lifecycle, client features, operations, contributing, ADRs, future-feature proposals)
  • Updates root README and CONTRIBUTING to point at the wiki
  • Adds Docker Compose for local client (:4444) + server (:5555) with health checks
  • Requires Node.js ≥ 26 (.nvmrc); CI split into separate server-test and client-build jobs on Node 26

Breaking changes

Change Impact
GraphQL removed Any GraphQL consumers will break
bitcoin and rickandmorty APIs removed Existing links to those endpoints 404
Node ≥ 26 required Older Node versions unsupported
json-server → custom router REST shapes preserved, but internals changed

Test plan

  • npm install && npm run dev — client at :4444, API at :5555
  • docker compose up — both services healthy, client waits on server healthcheck
  • Server: npm test in server/ (Jest suite + baseline snapshots)
  • Client: npm run build and npm run lint in client/
  • Playground: run fetch snippets against an endpoint; confirm sandbox output, JSON tree, and per-endpoint persistence
  • CRUD smoke test on a mutable API (e.g. coffee) — POST/PUT/PATCH/DELETE persist and /resetit restores
  • Confirm removed endpoints return 404: /bitcoin, /rickandmorty, GraphQL routes
  • Browse docs/README.md — links resolve, matches current code paths

jermbo added 25 commits May 31, 2025 08:00
@jermbo
docs: update contributing guidelines and add product requirements doc…
8cd567c 
…ument
@jermbo
feat: add docker setup for client and server containers
a1626eb
@jermbo
docs: add client and server documentation for SampleAPIs
518f448
@jermbo
docs: add application flow documentation for SampleAPIs
fa2ccfd
@jermbo
feat: integrate TanStack Query for data management and refactor Globa…
dcfd53f 
…lContext

- Added TanStack Query for managing server state, replacing the previous useFetch hook and related logic in GlobalContext.
- Updated package dependencies to use specific versions, including React 19 and TanStack libraries.
- Refactored API data fetching to utilize new hooks (useApiList, useApiCategories) for improved data handling.
- Removed obsolete useFetch hook and cleaned up GlobalContext to only manage UI state.
- Adjusted TypeScript configuration for module resolution and updated engine requirements in package.json.
- Documented the modernization plan for the frontend, outlining future phases for routing and styling improvements.
@jermbo
refactor: migrate to TanStack Router and restructure routing
eb5a0b1 
- Integrated TanStack Router, replacing React Router for improved routing capabilities.
- Removed the previous App component and routes configuration, transitioning to a file-based routing structure.
- Updated components to utilize the new routing system, including Link and useParams from TanStack Router.
- Added route definitions for main application pages, enhancing type safety and maintainability.
- Introduced a generated route tree for better organization and access to routes.
- Updated package.json to include necessary TanStack Router dependencies.
@jermbo
refactor: migrate styles from SCSS to CSS and clean up unused files
1f69388 
- Converted styles from SCSS to CSS, creating a more streamlined and maintainable structure.
- Removed obsolete SCSS files and functions, reducing complexity and improving performance.
- Updated component imports to reference new CSS files instead of SCSS.
- Introduced design tokens for consistent styling across the application.
- Enhanced the organization of styles by separating concerns into distinct CSS files for better readability.
@jermbo
feat: add self-hosted fonts for improved performance
e16818a 
- Introduced @fontsource packages for Montserrat Alternates and Roboto to eliminate render-blocking requests.
- Updated styles.css to import self-hosted font files, enhancing loading speed and layout stability.
@jermbo
refactor: enhance component structure and improve accessibility
d42452a 
- Updated main.tsx to enable smooth cross-page animations using the View Transitions API.
- Refactored APISearch, Nav, APIList, About, Docs, Home, StyleGuide components to use semantic HTML elements (e.g., <search>, <nav>, <section>) for better accessibility and SEO.
- Improved input elements with appropriate ARIA attributes and placeholders for enhanced user experience.
- Introduced responsive styles and transitions for a more cohesive design across different screen sizes.
@jermbo
feat: modernize server environment and CI configuration
579069e 
- Added .nvmrc to specify Node.js version 26 for consistency across environments.
- Updated GitHub Actions workflow to include separate jobs for server and client, both using Node.js 26.
- Enhanced CI to install server dependencies and run tests, ensuring compatibility and reliability.
- Introduced a Server Modernization Plan document outlining phases for upgrading dependencies and improving architecture.
- Updated Dockerfile to use Node.js 26, aligning with the new environment standards.
- Added baseline response snapshots for regression testing during future upgrades.
@jermbo
refactor: update server dependencies and improve API routing
2846750 
- Updated dependencies in package.json and package-lock.json to specific versions for better stability and performance.
- Replaced json-graphql-server with a custom jsonRouter for enhanced flexibility in API routing.
- Simplified API endpoint setup by removing unused code and improving data verification logic.
- Introduced a new utility for creating JSON-based routers, allowing for CRUD operations on JSON files.
@jermbo
refactor: remove deprecated APIs and clean up JSON files
922d3ec 
- Deleted unused API entries for Bitcoin and Rick and Morty from apiList.js and GeneratedAPIList.js.
- Removed bitcoin.json and its backup, streamlining the API structure.
- Updated checkdiff.sh to eliminate checks for removed JSON files.
- Enhanced coffee.json with improved descriptions and ingredient translations for better clarity.
- Corrected historical inaccuracies in presidents.json, including name and term adjustments for several presidents.
@jermbo
fix: update health check endpoint and remove GraphQL references
fd2cf27 
- Changed health check command in docker-compose.yml to point to the /health endpoint.
- Deleted GraphQL references from various files, including API descriptions and component props, to streamline the API focus on RESTful endpoints.
- Removed unused GraphQL links from apiList.js and related files, enhancing clarity and reducing confusion for users.
@jermbo
feat: add new API definitions for coffee endpoints
6f09829 
- Introduced 'Get Coffee' and 'Get Coffee Single' APIs for retrieving coffee details.
- Added 'Update Coffee Single' API for modifying coffee information.
- Created 'opencollection.yml' to manage API metadata and extensions.
@jermbo
refactor: remove GraphQL support and update documentation
3d29c3a 
- Eliminated all references to GraphQL across documentation files, including PRD, server documentation, and modernization plan.
- Streamlined API focus to emphasize RESTful endpoints, enhancing clarity for users.
- Updated technical constraints and future improvement sections to reflect the removal of GraphQL features.
@jermbo
feat: add new coffee API endpoints and restructure opencollection
7dcbfaa 
- Introduced 'Get Coffee' and 'Get Coffee Single' APIs for retrieving coffee details.
- Added 'Update Coffee Single' API for modifying coffee information.
- Created new opencollection.yml for endpoint configuration and removed the old opencollection.yml file.
@jermbo
feat: implement CodeMirror-based Playground component for API testing
0ac89ab 
- Added a new Playground component utilizing CodeMirror for code editing and execution within a sandboxed iframe.
- Replaced the previous Sandpack integration in APIDetails with the new Playground for a more streamlined user experience.
- Updated package.json to include necessary CodeMirror dependencies and removed Sandpack-related packages.
- Introduced Playground.css for styling the new component, enhancing the visual layout and user interaction.
@jermbo
feat: add JSON tree component and enhance Playground styling
af870c9 
- Introduced a new JsonTree component for displaying JSON data in a collapsible format within the Playground.
- Updated Playground.css to include styles for the new JsonTree component and improved overall layout with new tab and button styles.
- Enhanced the Playground component to support snippet loading and improved code editing experience with better state management.
@jermbo
chore: update Node.js version and optimize Dockerfile for production
b793299 
- Updated the Node.js version requirement in package.json to 26 for compatibility.
- Modified the Dockerfile to install only production dependencies using `npm ci --omit=dev`, reducing image size.
- Changed the application start command to use `npm start` for production readiness.
- Enhanced the server's security by running as a non-root user and setting the NODE_ENV to production.
- Removed the express-slow-down dependency from package.json and package-lock.json for a leaner setup.
@jermbo
refactor: replace ESLint with OXLint configuration and remove unused …
2ccbd3e 
…files

- Deleted the existing ESLint configuration file and replaced it with a new OXLint configuration file for improved linting capabilities.
- Updated the Dockerfile to set the NODE_ENV to production and changed the command to serve the production build.
- Removed the CodepenWrapper component and the useLocalStorage hook as they were no longer needed.
- Enhanced the API details page to handle loading and error states more effectively.
- Refactored the API list page to optimize filtering logic using useMemo for better performance.
- Made various accessibility improvements across components, including aria attributes for better screen reader support.
- Cleaned up CSS styles for better layout and responsiveness.
@jermbo
enhance: add header to loading state in APIDetails and update CSS for…
5ef7b59 
… page header

- Wrapped the loading message in a header element for better semantic structure in the APIDetails component.
- Added a minimum height to the page header in CSS to improve layout consistency.
@jermbo
docs: update CONTRIBUTING and README for clarity and structure
20edb9b 
- Enhanced the CONTRIBUTING.md file with a link to the project wiki for better guidance on project architecture and data lifecycle.
- Improved the README.md to clarify the purpose of SampleAPIs and how to use the service, including updated code examples and documentation links.
- Removed outdated sections and streamlined the content for better readability and user engagement.
- Added a new section in the README for documentation navigation to assist users in finding relevant information quickly.
@jermbo
chore: update package versions to 3.0.0 across all modules
166de13 
- Bumped the version number to 3.0.0 in package.json files for the main application, client, and server to reflect the latest release.
@jermbo
docs: add future features documentation and proposals
35ced98 
- Introduced a new section for proposed features in the documentation, outlining various enhancements aimed at improving the learning experience with SampleAPIs.
- Added individual documentation pages for each proposed feature, including Auth Training Wheels, Error Practice Routes, Guided Challenges, HTTP Inspector, Multi-Language Snippets, Query Builder, Response Shape Viewer, Scratch Endpoints, and Shareable Playground Links.
- Each proposal includes a description, problem statement, proposed solution, fit with current code, effort and risk assessment, and open questions for further consideration.
@jermbo
docs: enhance error response documentation and clarify validation beh…
203fcb0 
…avior

- Added details to the error responses documentation regarding the behavior of writes to unknown resources, specifying that they return a `400` status when validation fails.
- Updated the CRUD and validation documentation to include information about handling writes to resources with no existing records.
- Clarified the pagination documentation to specify that the `Link` header only includes applicable URLs based on the current page.
- Expanded the testing documentation to include a new section on response baseline snapshots for regression testing.
@jermbo jermbo requested a review from thedamian July 10, 2026 00:55
@jermbo
chore: update package-lock.json and remove package-lock from .gitignore
4dc0cee 
- Added a new package-lock.json file for the client to manage dependencies.
- Updated the server's package-lock.json to reflect version changes and clean up unused dependencies.
- Removed package-lock.json from .gitignore to ensure it is tracked in version control.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@thedamian thedamian Awaiting requested review from thedamian

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@jermbo