https://github.com/fezcode/fezcode.github.io
A brutally interactive developer portfolio and project showcase. Features a 3D knowledge graph, dynamic visual themes, and a suite of built-in mini-apps, serving as a digital garden for my code and creativity.
https://github.com/fezcode/fezcode.github.io
apps blogpost canvas canvas2d frontend javascript piml portfolio portfolio-project portfolio-site portfolio-website react reactjs website
Last synced: 3 months ago
JSON representation
A brutally interactive developer portfolio and project showcase. Features a 3D knowledge graph, dynamic visual themes, and a suite of built-in mini-apps, serving as a digital garden for my code and creativity.
- Host: GitHub
- URL: https://github.com/fezcode/fezcode.github.io
- Owner: fezcode
- Created: 2025-10-15T01:59:39.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-03-28T22:01:29.000Z (3 months ago)
- Last Synced: 2026-03-29T00:51:29.739Z (3 months ago)
- Topics: apps, blogpost, canvas, canvas2d, frontend, javascript, piml, portfolio, portfolio-project, portfolio-site, portfolio-website, react, reactjs, website
- Language: JavaScript
- Homepage: https://fezcode.com/
- Size: 265 MB
- Stars: 6
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
Awesome Lists containing this project
README
# Fezcodex
### What is this?
Imagine you have a giant digital toy box. Inside, you keep the cool things you've built, the stories you've written, and a diary of all the interesting things you've learned. Fezcodex is that toy box. It is a special website that works like a personal museum on the internet. It is not just a boring page; it has moving parts, secret "Easter eggs," and little mini-apps like a sound mixer and a knowledge graph.
---
## Key Features
- **Digital Garden**: A space where blog posts and "logs" (mini-diaries about books, movies, or games) grow.
- **Knowledge Graph**: A 3D interactive visualization of how all content on the site is interconnected.
- **Project Archives**: A showcase of all the coding experiments and software I've built.
- **Mini-Apps**: Built-in tools like an Atmosphere Mixer, Cloud Music Player, Typing Tester, and a digital Rotary Phone.
- **Visual Magic**: Change how the whole site looks using the "Visual Matrix"—make it look like an old computer (CRT), a blueprint, or even a comic book.
- **Achievements**: Just like a video game, you get little trophies for exploring the site and finding hidden things.
---
## Tech Stack (The Lego Bricks)
- **Frontend**: React 19, Tailwind CSS, and Framer Motion for smooth animations.
- **3D & Graphics**: Three.js and react-force-graph-3d for the knowledge graph.
- **Content**: Markdown and **PIML** (Plain Old Markup Language) for structured content.
- **Build Tools**: Craco (CRA Configuration Override) for custom build pipelines.
- **Persistence**: Local Storage for settings, achievements, and persistent state.
- **AI Tooling**: **Model Context Protocol (MCP)** server for automated content management.
---
## Model Context Protocol (MCP)
Fezcodex includes a custom MCP server to assist AI agents (like Gemini) in managing content.
### Tools Provided:
- `create_blog_post`: Automates the creation of blog posts, including file generation, metadata registry updates, and RSS/Sitemap regeneration.
### Integration with Gemini CLI:
To use this server with your Gemini CLI, run:
```bash
gemini mcp add fezcodex-blog-writer --command "node scripts/mcp-server/index.mjs"
# or
gemini mcp add --scope project fezcodex npm run mcp
```
Once added, the AI can create blog posts directly through its toolset.
## Project Structure
- `src/app/`: Domain logic, core features, and views (Achievements, OS, Command Palette, etc.).
- `src/components/`: Reusable UI components (Buttons, Modals, Cards).
- `src/context/`: Global state management (Visual Settings, Toast, Animation).
- `public/`: The "pantry" where all actual content (PIML files, text, images, sounds) is stored.
- `scripts/`: Helper programs for generating RSS, sitemaps, and wallpapers.
---
## Technical Setup
### Prerequisites
Make sure you have Node.js installed on your computer.
### 1. Get the code
```bash
git clone https://github.com/fezcode/fezcode.github.io.git
cd fezcode.github.io
```
### 2. Install the tools
```bash
npm install
```
### 3. Start the engine
```bash
npm start
```
This will open the site at http://localhost:3000.
---
## Routing and SEO
This project uses `BrowserRouter` for clean URLs. To support this on static hosts like GitHub Pages, we use `react-snap` to pre-render routes into static HTML files during the build process.
### Deployment
The standard `npm run deploy` command handles the build, pre-rendering, and deployment to GitHub Pages automatically.
```bash
npm run deploy
```
### Content Syncing
Stories are managed via git subtrees. Because subtree remotes are not tracked by git, you must initialize the remote once after cloning:
- `npm run init-stories`: Initialize the stories remote URL (only needed once).
- `npm run pull-stories`: Sync stories from the remote repository.
- `npm run push-stories`: Push local story changes to the remote repository.
---
## Rules of the House
- **Contributing:** Please read our [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on commit messages and content updates.
- **Styling**: We use Tailwind. Keep it **Brutalist** yet polished.
- **Components**: Always use `CustomDropdown`, `BrutalistDialog`, and `CustomSlider` for UI consistency.
- **Icons**: We use `@phosphor-icons/react`. Always use the ones ending in `Icon` (e.g., `CpuIcon`).
- **Logic**: Use Context for global settings like Visual Effects and Achievements.
---
## Developer Guide: How to Update Things
If you are modifying or expanding the functionality of Fezcodex, follow these specific architectural patterns:
### 1. Adding or Updating Commands
Commands are used in the **Commands Page** and the **Command Palette**. To update them, you must touch three places:
- **`src/data/commands.js`**: Update the UI data (title, description, icon color) for the `/commands` page.
- **`src/hooks/useCommandRegistry.js`**: Implement the actual logic/handler for what the command does.
- **`src/hooks/useSearchableData.js`**: Update the `customCommands` list so the Command Palette (`Ctrl + K`) can "find" the command.
### 2. Updating Search Data
The site-wide search (Command Palette and Search bar) is powered by a unified registry:
- **Automatic:** Blog posts, Projects, and Logs are automatically indexed from their respective `.json` and `.piml` files in the `public/` directory.
- **Manual:** Static pages and custom commands must be manually added to the `staticRoutes` or `customCommands` lists in `src/hooks/useSearchableData.js`.
### 3. Modifying Visual Themes (Brutalist vs. Luxe)
Every core component should be **Theme-Aware**:
- **Switcher Components:** Components like `CommandPalette.jsx`, `SidePanel.jsx`, and `GenericModal.jsx` act as controllers. They detect `fezcodexTheme` and render either a `BrutalistX` or `LuxeX` variant.
- **Universal Styles:** Prefer the `variant="brutalist"` or `variant="paper"` props for shared components like `CustomDropdown` to maintain consistency.
### 4. Global State & Persistence
- Use `VisualSettingsContext.jsx` for any UI state that needs to survive a page refresh (Invert mode, Theme selection, etc.).
- Use `usePersistentState` hook to automatically sync your context variables with `localStorage`.
### 5. AI-Assisted Content Creation (MCP)
If you are using an AI agent with MCP support:
- **Blog Posts:** Use the `create_blog_post` tool provided by the local MCP server. It handles file creation, metadata indexing, and build script execution in one step.
- **Verification:** Always run `npm run lint` after AI-generated changes to ensure style compliance.
---
## Github Pages Configuration
1. Deploy from a branch.
2. Select the `gh-pages` branch
3. Add `fezcode.com` as the custom domain.
---
Created by [Ahmed Samil Bulbul](https://fezcode.com).