|
| 1 | +# Atlas Channel Management Guide |
| 2 | + |
| 3 | +## Overview |
| 4 | +Atlas uses a color-coded channel system to categorize articles by topic. **Each article belongs to exactly one channel** - its primary category. Each channel has a specific color, icon, and focus area. This guide provides clear procedures for frontend teams to maintain channel assignments and keep the system organized. |
| 5 | + |
| 6 | +## Channel System |
| 7 | + |
| 8 | +### Available Channels |
| 9 | + |
| 10 | +| Channel | Color | Icon | Focus Area | Examples | |
| 11 | +|---------|-------|------|------------|----------| |
| 12 | +| **Physics** | `#3b82f6` (blue) | Atom ⚛️ | Physics, quantum mechanics, energy | Feynman consciousness, quantum computation | |
| 13 | +| **Philosophy** | `#8b5cf6` (purple) | Brain 🧠 | Philosophy, ethics, consciousness | Philosophical dialogues, moral reasoning | |
| 14 | +| **Mathematics** | `#10b981` (emerald) | Calculator 🧮 | Math, computation, logic, algorithms | Turing machines, computational thinking | |
| 15 | +| **Biology** | `#f59e0b` (amber) | DNA 🧬 | Biology, evolution, life sciences | Darwin evolution, biological systems | |
| 16 | +| **Ethics** | `#ef4444` (red) | Scale ⚖️ | Ethics, morality, justice, governance | Institutional design, moral philosophy | |
| 17 | +| **Editorial** | `#ec4899` (pink) | Zap ⚡ | Editorial content, commentary, analysis | Ruixen's posts, meta-discussions | |
| 18 | + |
| 19 | +### Channel Assignment Rules |
| 20 | + |
| 21 | +#### Explicit Assignment (Recommended) |
| 22 | +Add a single `channel` field to article frontmatter: |
| 23 | + |
| 24 | +```yaml |
| 25 | +--- |
| 26 | +title: "Your Article Title" |
| 27 | +date: "2025-09-24" |
| 28 | +tags: ["tag1", "tag2"] |
| 29 | +channel: "biology" # ← Add this line (single channel) |
| 30 | +type: "monologue" |
| 31 | +author: "Author Name" |
| 32 | +--- |
| 33 | +``` |
| 34 | + |
| 35 | +#### Automatic Detection (Fallback) |
| 36 | +If no explicit channel is defined, the system automatically detects the primary channel based on: |
| 37 | +- **Tags**: Matches specific keywords in tags array |
| 38 | +- **Content**: Searches article content for relevant terms |
| 39 | +- **Title**: Analyzes title for key domain indicators |
| 40 | +- **Priority**: Biology > Physics > Mathematics > Ethics > Editorial > Philosophy |
| 41 | + |
| 42 | +## Frontend Team Procedures |
| 43 | + |
| 44 | +### 1. New Article Channel Assignment |
| 45 | + |
| 46 | +**When adding a new article:** |
| 47 | + |
| 48 | +1. **Read the article** to understand its primary theme |
| 49 | +2. **Select the single most relevant channel** (be decisive!) |
| 50 | +3. **Add explicit channel** to frontmatter: |
| 51 | + ```yaml |
| 52 | + channel: "biology" |
| 53 | + ``` |
| 54 | +4. **Verify badge appears** correctly in Atlas feed and Explore table |
| 55 | +
|
| 56 | +### 2. Channel Updates |
| 57 | +
|
| 58 | +**When updating existing articles:** |
| 59 | +
|
| 60 | +1. **Review current assignment** in article frontmatter |
| 61 | +2. **Update channel** as needed: |
| 62 | + ```yaml |
| 63 | + # Before |
| 64 | + channel: "physics" |
| 65 | + |
| 66 | + # After |
| 67 | + channel: "consciousness" |
| 68 | + ``` |
| 69 | +3. **Test in both views**: Atlas feed (single badge top-right) and Explore table (channels column) |
| 70 | +
|
| 71 | +### 3. Channel System Maintenance |
| 72 | +
|
| 73 | +**Monthly review process:** |
| 74 | +
|
| 75 | +1. **Audit article distributions**: |
| 76 | + ```bash |
| 77 | + # Check channel balance |
| 78 | + grep -r "channel:" src/content/ | sort | uniq -c |
| 79 | + ``` |
| 80 | +2. **Update channel counts** in `channels-sidebar.tsx` if needed |
| 81 | +3. **Review auto-detection rules** for accuracy |
| 82 | + |
| 83 | +### 4. Quality Guidelines |
| 84 | + |
| 85 | +**Channel Assignment Best Practices:** |
| 86 | + |
| 87 | +- ✅ **Focus on THE primary theme**: What is the main topic? |
| 88 | +- ✅ **Consider target audience**: Which channel would readers expect to find this in? |
| 89 | +- ✅ **Balance distribution**: Avoid overloading single channels |
| 90 | +- ✅ **Be decisive**: Choose the most important/relevant channel |
| 91 | +- ❌ **Don't overthink**: One channel per article keeps it clean |
| 92 | +- ❌ **Avoid generic assignments**: Be specific to content |
| 93 | + |
| 94 | +**Examples of Good Channel Assignments:** |
| 95 | + |
| 96 | +```yaml |
| 97 | +# Darwin evolution article - clearly about biology |
| 98 | +channel: "biology" |
| 99 | + |
| 100 | +# Turing computation monologue - primarily mathematical |
| 101 | +channel: "mathematics" |
| 102 | + |
| 103 | +# Feynman consciousness piece - physics perspective on mind |
| 104 | +channel: "physics" |
| 105 | + |
| 106 | +# Ethics governance dialogue - moral/political philosophy |
| 107 | +channel: "ethics" |
| 108 | + |
| 109 | +# Editorial piece by Ruixen - meta-commentary |
| 110 | +channel: "editorial" |
| 111 | + |
| 112 | +# Current Article Distribution: |
| 113 | +# - Biology: 2 articles (Darwin evolution content) |
| 114 | +# - Physics: 1 article (Feynman) |
| 115 | +# - Mathematics: 1 article (Turing) |
| 116 | +# - Ethics: 1 article (Governance) |
| 117 | +# - Editorial: 1 article (Ruixen bridges piece) |
| 118 | +``` |
| 119 | + |
| 120 | +## Technical Implementation |
| 121 | + |
| 122 | +### Component Structure |
| 123 | +``` |
| 124 | +src/ |
| 125 | +├── components/ |
| 126 | +│ ├── channel-badge.tsx # Badge components |
| 127 | +│ └── channels-sidebar.tsx # Sidebar with channel definitions |
| 128 | +├── app/ |
| 129 | +│ ├── atlas/page.tsx # Atlas feed with badges |
| 130 | +│ └── explore/page.tsx # Explore table with channels column |
| 131 | +└── content/ |
| 132 | + ├── monologues/ # Articles with channel frontmatter |
| 133 | + └── dialogues/ |
| 134 | +``` |
| 135 | + |
| 136 | +### Channel Badge Features |
| 137 | +- **Color-coded**: Matches channel system colors perfectly |
| 138 | +- **Single badge**: Clean, uncluttered display |
| 139 | +- **Responsive**: Different sizes (sm/md/lg) |
| 140 | +- **Hover effects**: Subtle animations and scaling |
| 141 | +- **Text-only**: No icons by default for minimal design |
| 142 | + |
| 143 | +### Badge Placement |
| 144 | +- **Atlas Feed**: Single badge in top-right corner of article cards |
| 145 | +- **Explore Table**: Single badge in dedicated "Channels" column |
| 146 | +- **Article Pages**: Could be added to headers/footers |
| 147 | + |
| 148 | +## Automation Opportunities |
| 149 | + |
| 150 | +### Current System |
| 151 | +- ✅ **Explicit channel**: Direct frontmatter specification (singular) |
| 152 | +- ✅ **Auto-detection**: Prioritized fallback logic based on tags/content/title |
| 153 | +- ✅ **Component reuse**: Centralized badge components |
| 154 | +- ✅ **Clean UI**: Single badge per article for uncluttered design |
| 155 | + |
| 156 | +### Future Enhancements |
| 157 | +- 🔄 **Content analysis**: ML-based primary topic classification |
| 158 | +- 🔄 **Bulk updates**: Scripts for batch single channel assignments |
| 159 | +- 🔄 **Validation**: Pre-commit hooks to check channel assignments |
| 160 | +- 🔄 **Analytics**: Track channel engagement and distribution |
| 161 | + |
| 162 | +## Quick Reference Commands |
| 163 | + |
| 164 | +```bash |
| 165 | +# Find all articles with explicit channels |
| 166 | +grep -r "channel:" src/content/ |
| 167 | + |
| 168 | +# Count articles per channel |
| 169 | +grep -r "channel:" src/content/ | cut -d'"' -f2 | sort | uniq -c |
| 170 | + |
| 171 | +# Find articles without explicit channels (using auto-detection) |
| 172 | +grep -L "channel:" src/content/**/*.md |
| 173 | + |
| 174 | +# Current channel distribution |
| 175 | +# Biology: 2, Mathematics: 1, Physics: 1, Ethics: 1, Editorial: 1 |
| 176 | + |
| 177 | +# Update article to new channel |
| 178 | +sed -i 's/channel: "old"/channel: "new"/' src/content/path/to/article.md |
| 179 | +``` |
| 180 | + |
| 181 | +## Support & Troubleshooting |
| 182 | + |
| 183 | +### Common Issues |
| 184 | +1. **Badge not appearing**: Check `channel: "value"` syntax and spelling |
| 185 | +2. **Wrong colors**: Verify channel ID matches `CHANNELS` constant exactly |
| 186 | +3. **"Uncategorized" showing**: Article has no explicit channel and auto-detection failed |
| 187 | +4. **Layout issues**: Test responsive behavior on different screen sizes |
| 188 | + |
| 189 | +### Channel System Files |
| 190 | +- `src/components/channel-badge.tsx` - Single badge component and logic |
| 191 | +- `src/components/channels-sidebar.tsx` - Channel definitions and colors |
| 192 | +- `src/app/atlas/page.tsx` - Atlas feed integration (top-right badge) |
| 193 | +- `src/app/explore/page.tsx` - Explore table integration (channels column) |
| 194 | + |
| 195 | +## Decision Rationale |
| 196 | + |
| 197 | +**Why Single Channel?** |
| 198 | +- ✅ **Cleaner UI**: No visual clutter from multiple badges |
| 199 | +- ✅ **Better navigation**: Users expect articles in one primary category |
| 200 | +- ✅ **Easier management**: Forces decisive content categorization |
| 201 | +- ✅ **More useful**: Channels as categories, not tags |
| 202 | +- ✅ **Scalable**: Works well as content library grows |
| 203 | + |
| 204 | +--- |
| 205 | + |
| 206 | +**Last Updated**: September 24, 2025 |
| 207 | +**Version**: 2.0 (Single Channel System) |
| 208 | +**Maintained by**: Frontend Team |
| 209 | + |
| 210 | +*This guide ensures consistent, maintainable channel management across the Atlas platform. Each article gets exactly one channel - its primary home. For questions or updates, consult the frontend team lead.* |
0 commit comments