diff --git a/.cursor/commands/about.md b/.cursor/commands/about.md new file mode 100644 index 0000000..e69de29 diff --git a/README.md b/README.md index 7191d4f..aa3c48e 100644 --- a/README.md +++ b/README.md @@ -1,42 +1,107 @@ # Consciousness Atlas -Interactive chart visualization project built with Vite, TypeScript, and ECharts. +An interactive web application that visualizes Robert Lawrence Kuhn's "Landscape of Consciousness" - mapping over 325 theories of phenomenal consciousness in an explorable sunburst chart. -## Features +## Tech Stack & Architecture -- โšก **Super fast development** with Vite -- ๐ŸŽฏ **TypeScript** for strong typing and better DX -- ๐Ÿ“Š **ECharts integration** with tree-shaking for optimal bundle size -- ๐ŸŽจ **Canvas renderer** for crisp, scalable charts -- ๐Ÿ”ง **Clean imports** with vite-tsconfig-paths -- ๐Ÿ“ฑ **Responsive design** with automatic resize handling +- **Frontend**: TypeScript + Vite with ESBuild +- **Charts**: ECharts 6.0 with Sunburst visualization (SVG/Canvas renderers) +- **Styling**: SCSS with responsive design and mobile optimization +- **Deployment**: Vercel with SPA routing and file-based routing +- **Form Submissions**: Telegram Bot API integration for feedback collection +- **Dependencies**: Minimal - only ECharts, Vite, TypeScript, and SCSS -## Tech Stack +## Technical Features -- **Bundler**: Vite (super fast dev + optimized build) -- **Language**: TypeScript (strong typing for ECharts config + DX) -- **Charts**: ECharts with tree-shaking (only import what you need) -- **Renderer**: SVG (scales well for screenshots/exports) -- **Build**: ESBuild for fast builds +- ๐Ÿš€ **Minimal Bundle Size** - Tree-shaking and code splitting (only SunburstChart, SVGRenderer, CanvasRenderer, TitleComponent) +- ๐Ÿ“ฑ **Responsive Design** - Dynamic label positioning and mobile-optimized interactions +- ๐ŸŽจ **Dynamic Color System** - Mystic-themed palette with automatic hierarchy-based color variations +- ๐Ÿ”„ **SPA Routing** - Client-side routing with history API fallback +- ๐Ÿ“Š **High Performance** - SVG renderer for crisp scaling, Canvas fallback +- ๐Ÿค– **Telegram Integration** - Form submissions sent directly to Telegram bot + +## Form Submissions & Telegram Integration + +The feedback form uses a serverless API endpoint (`api/submit.ts`) that forwards submissions to a Telegram bot: + +- **API Endpoint**: `/api/submit` - Handles POST requests with form data +- **Telegram Bot**: Sends formatted messages to a designated Telegram chat +- **Error Handling**: Graceful fallback with user feedback +- **Security**: Basic validation and sanitization of form inputs + +## Analytics & Mixpanel Integration + +The application includes comprehensive analytics tracking using Mixpanel: + +### Setup +1. Create a Mixpanel project and get your project token +2. Set the environment variable: `VITE_MIXPANEL_TOKEN=your_token_here` +3. Analytics will automatically initialize in production mode + +### Tracked Events + +1. **Page Views** - Each theory navigation is tracked as a page view + - Event: `Page View` + - Properties: `theory_name`, `category`, `subcategory`, `page_type` + +2. **Click Tracking** - Various user interactions + - Event: `Click` + - Elements tracked: + - Feedback button clicks + - GitHub link clicks + - Kuhn paper link clicks + - Twitter/X link clicks + - "Read more" link clicks + - Properties: `element`, `position`, `link_url`, `click_type` + +3. **Form Submissions** - Feedback form interactions + - Event: `Form Submission` + - Properties: `form_type`, `success`, `error_message`, `submission_type` + +### Analytics Configuration +- **Debug Mode**: Enabled in development, disabled in production +- **Persistence**: Uses localStorage for session persistence +- **Tracking**: Only tracks in production when token is provided +- **Properties**: Includes timestamp, URL, user agent, and additional custom properties ## Project Structure ``` src/ -โ”œโ”€โ”€ components/ # Reusable UI components -โ”œโ”€โ”€ config/ # Chart configurations -โ”‚ โ””โ”€โ”€ chartConfig.ts # ECharts options and data -โ”œโ”€โ”€ types/ # TypeScript type definitions -โ”œโ”€โ”€ main.ts # Main application entry point -โ””โ”€โ”€ style.css # Global styles +โ”œโ”€โ”€ components/ # UI components +โ”‚ โ”œโ”€โ”€ TheoryChart.ts # Main sunburst chart component +โ”‚ โ”œโ”€โ”€ SearchBar.ts # Theory search functionality +โ”‚ โ”œโ”€โ”€ FormPopup.ts # Feedback form modal +โ”‚ โ””โ”€โ”€ ItemDetailsPanel.ts # Theory detail viewer +โ”œโ”€โ”€ config/ # Configuration files +โ”‚ โ”œโ”€โ”€ appConfig.ts # App settings and environment variables +โ”‚ โ””โ”€โ”€ chartConfig.ts # Chart data, colors, and ECharts options +โ”œโ”€โ”€ data/ # Data files +โ”‚ โ”œโ”€โ”€ theoryNames.ts # Theory name mappings +โ”‚ โ””โ”€โ”€ THEORY.md # Theory documentation +โ”œโ”€โ”€ pages/ # Page-specific styles +โ”‚ โ””โ”€โ”€ theory.scss # Theory detail page styling +โ”œโ”€โ”€ styles/ # Global styles +โ”‚ โ”œโ”€โ”€ main.scss # Main stylesheet +โ”‚ โ””โ”€โ”€ _mixins.scss # SCSS mixins +โ”œโ”€โ”€ types/ # TypeScript definitions +โ”‚ โ”œโ”€โ”€ theory.ts # Mind Theory Taxon Schema (MTTS) interface +โ”‚ โ””โ”€โ”€ chart.ts # Chart-related types +โ”œโ”€โ”€ utils/ # Utility functions +โ”‚ โ”œโ”€โ”€ routing.ts # Client-side routing +โ”‚ โ”œโ”€โ”€ globalState.ts # Application state management +โ”‚ โ”œโ”€โ”€ chartUtils.ts # Chart helper functions +โ”‚ โ”œโ”€โ”€ slugUtils.ts # URL slug utilities +โ”‚ โ””โ”€โ”€ apiMock.ts # Mock API for development +โ””โ”€โ”€ main.ts # Application entry point ``` ## Getting Started ### Prerequisites -- Node.js 18+ -- npm or yarn +- Node.js 22.x +- npm ### Installation @@ -44,7 +109,7 @@ src/ # Install dependencies npm install -# Start development server +# Start development server (runs on port 8080) npm run dev # Build for production @@ -52,45 +117,91 @@ npm run build # Preview production build npm run preview + +# Type checking +npm run type-check ``` ## Development The project uses: -- **Path mapping** for clean imports (`@/components/*`, `@/config/*`) -- **Tree-shaking** - only import the ECharts modules you need +- **Path mapping** for clean imports (`@/components/*`, `@/config/*`, `@/types/*`) +- **Tree-shaking** - Only imports required ECharts components (SunburstChart, SVGRenderer, CanvasRenderer) - **Code splitting** - ECharts is automatically chunked for better performance +- **SCSS** - Modular styling with mixins and responsive design +- **TypeScript** - Strict typing ## Chart Configuration -Chart options are kept in a separate config file (`src/config/chartConfig.ts`) for maintainability. You can easily: +The sunburst chart is configured in `src/config/chartConfig.ts`: -- Modify chart data -- Change chart types -- Update styling and themes -- Add new chart configurations +- **Data Structure**: Hierarchical theory organization (10 main categories โ†’ subcategories โ†’ individual theories) +- **Color Palette**: Mystic-themed colors with automatic lightening/desaturation for hierarchy levels +- **Label Positioning**: Dynamic positioning based on device type and hierarchy level +- **Interactive Features**: Tooltips, click handlers, and responsive behavior ## Deployment -This project can be easily deployed on: -- **Vercel** - `npm run build` then deploy the `dist` folder -- **Netlify** - Connect your repo and it will auto-deploy -- **GitHub Pages** - `npm run build` then push the `dist` folder to gh-pages branch +The project is configured for Vercel deployment: + +```bash +# Build for production +npm run build + +# Deploy to Vercel (if using Vercel CLI) +vercel --prod +``` + +The `vercel.json` configuration includes: +- SPA routing with history API fallback +- Asset caching headers +- Build command configuration ## Performance Features -- **Tree-shaking**: Only loads required ECharts components -- **SVG renderer**: Better for static/interactive charts -- **Code splitting**: Automatic chunking of heavy dependencies -- **Optimized builds**: ESBuild for fast production builds +- **Tree-shaking**: Only loads required ECharts components (SunburstChart, SVGRenderer, CanvasRenderer, TitleComponent) +- **Code splitting**: ECharts automatically chunked for better loading performance +- **Responsive rendering**: SVG renderer for crisp scaling, Canvas fallback +- **Optimized builds**: ESBuild for fast development and production builds +- **Mobile optimization**: Dynamic label visibility and positioning ## Customization -To add new chart types: -1. Import the required ECharts components in `main.ts` -2. Add the component to `echarts.use()` -3. Create new chart options in `chartConfig.ts` -4. Update the chart type in the series configuration +To modify the chart: + +1. **Data**: Edit `baseData` in `src/config/chartConfig.ts` +2. **Colors**: Modify `mysticPalette` and color utility functions +3. **Styling**: Update SCSS files in `src/styles/` and `src/pages/` +4. **Chart Options**: Modify `getChartOptions()` function +5. **Theory Data**: Add entries to data files in `src/data/` + +--- + +## About the Consciousness Atlas + +The Consciousness Atlas is a free web app that transforms Kuhn's 2024 academic paper into an interactive visualization. It presents theories of consciousness organized along a spectrum from most physical (Materialism) to least physical (Idealism), allowing users to explore the field visually and access detailed theory entries. + +## Features + +- ๐Ÿง  **Interactive Sunburst Chart** - Visualize 325+ consciousness theories in a hierarchical layout +- ๐Ÿ“š **Detailed Theory Entries** - Click any theory to read structured summaries with sources +- ๐Ÿ” **Search Functionality** - Find specific theories quickly +- ๐Ÿ“ฑ **Responsive Design** - Optimized for desktop and mobile viewing + +## Theory Data + +Theories are organized using Kuhn's taxonomy with structured data following the Mind Theory Taxon Schema (MTTS): + +- **IdAndClass**: Theory title, summary, thinkers, category classification +- **ConceptualGround**: Ontological status, mind-body relationship, qualia accounts +- **MechanismAndDynamics**: Scope, mechanisms, evidence, evolutionary accounts +- **EmpiricsAndCritiques**: Testability, criticisms, limitations +- **Implications**: Stances on AI consciousness, survival after death, meaning +- **RelationsAndSources**: Related theories and academic references + +## Academic Context + +Based on Robert Lawrence Kuhn's 2024 paper "A Landscape of Consciousness" published in Progress in Biophysics and Molecular Biology. The Atlas follows Kuhn's "collect and categorize, not assess and adjudicate" approach, providing a neutral visualization of the consciousness research landscape. ## License diff --git a/api/submit.ts b/api/submit.ts index d7ad55a..efe61d0 100644 --- a/api/submit.ts +++ b/api/submit.ts @@ -1,7 +1,6 @@ import type { VercelRequest, VercelResponse } from '@vercel/node' export default async function handler(req: VercelRequest, res: VercelResponse) { - // Only allow POST requests if (req.method !== 'POST') { return res.status(405).json({ error: 'Method not allowed' }) } @@ -9,23 +8,22 @@ export default async function handler(req: VercelRequest, res: VercelResponse) { try { const { name, email, message } = req.body - // Validate required fields if (!message || !message.trim()) { return res.status(400).json({ error: 'Message is required' }) } - // Get environment variables const tgToken = process.env.TG_BOT_TOKEN const chatId = process.env.TG_CHAT_ID - // If Telegram is configured, send message + const randomEmojis = ['๐Ÿง ', '๐Ÿ’ญ', '๐Ÿค”', '๐Ÿ’ก', '๐Ÿ’ฅ', '๐Ÿ”', '๐Ÿ”ฆ', '๐Ÿ”ฌ', '๐Ÿ”ญ', '๐Ÿ”ฎ', '๐Ÿ”ฅ', '๐Ÿ”’', '๐Ÿ”–', '๐Ÿ”—'] + const randomIndex = Math.floor(Math.random() * randomEmojis.length) + const randomEmoji = randomEmojis[randomIndex] + if (tgToken && chatId) { - const telegramMessage = `๐Ÿ“จ New form submission from C-Atlas -${name ? `Name: ${name}` : 'Name: Not provided'} -${email ? `Email: ${email}` : 'Email: Not provided'} -Message: ${message} - -Timestamp: ${new Date().toISOString()}` + const telegramMessage = ` + ${randomEmoji} ๐Ÿ“จ ${message} + ${name ? `From: ${name}` : ''}${email ? `(${email})` : ''} + ` const telegramResponse = await fetch(`https://api.telegram.org/bot${tgToken}/sendMessage`, { method: 'POST', @@ -44,7 +42,6 @@ Timestamp: ${new Date().toISOString()}` return res.status(500).json({ error: 'Failed to send notification' }) } } else { - // Log to console if Telegram is not configured console.log('Form submission received:', { name: name || 'Not provided', email: email || 'Not provided', @@ -53,7 +50,6 @@ Timestamp: ${new Date().toISOString()}` }) } - // Return success response return res.status(200).json({ success: true, message: 'Form submitted successfully' diff --git a/index.html b/index.html index fe050c9..9b8bcb1 100644 --- a/index.html +++ b/index.html @@ -350,7 +350,7 @@
-
@@ -394,6 +394,24 @@ Feedback + +
@@ -509,7 +527,7 @@

How many theories does the Atlas include?

- The Atlas visualizes over 325 individual theories, grouped into ten + The Atlas visualizes over 220 individual theories, grouped into ten broad categories.

@@ -530,15 +548,6 @@ where available.

- -
-

Can I use the Atlas data for research?

-

- Yes. Cite the Atlas and the original sources. If you plan wide - redistribution or commercial use, please contact the team for - licensing details. -

-