Flash Feather 2.7 🪶

An experimental LLM-friendly web framework designed for AI-assisted development.

Flash Feather combines stable, well-documented web technologies (FastAPI + Jinja2 + Lit.js) that work reliably with LLMs, avoiding the knowledge cutoff issues of rapidly-evolving modern frameworks.

🚧 Community Project: This is an experimental framework. The original creator has moved on - contributors welcome to continue development!

🎯 Why Flash Feather?

Problem: Modern JS frameworks update rapidly, making LLM code generation unreliable due to knowledge cutoffs.

Solution: Curated stack of stable, mature technologies that LLMs understand well:

• Backend: Python FastAPI (well-documented, stable API)
• Frontend: Lit.js (minimal, standards-based web components)
• Templating: Jinja2 (mature, widely-used)
• Database: SQLite + SQLAlchemy (stable ORM patterns)

✨ Key Features

• 🤖 LLM-Optimized: Patterns and technologies LLMs handle well
• 🆔 UID Component System: Prevents CSS conflicts with unique identifiers (cc01, cc02...)
• 🎨 CSS Variables Theming: Consistent, maintainable styling system
• 🔐 Built-in Auth: JWT + OAuth with HTTP-only cookies
• 🌍 Environment-Aware: Auto-configures for dev/production
• 📝 Schema-Free APIs: Direct request/response without separate schema files
• ⚡ Zero-Config: Auto-creates admin account and handles file storage

🛠 Tech Stack

Backend:  FastAPI + SQLAlchemy + JWT Auth + Google OAuth
Frontend: Lit.js Web Components + CSS Variables
Database: SQLite (dev) / Production-ready paths
Styling:  Component-scoped CSS with UID isolation

📁 Project Structure

flash-feather-starter/
├── app/
│   ├── main.py                 # FastAPI app entry point
│   ├── database.py             # Environment-aware DB setup
│   ├── models.py               # SQLAlchemy models
│   ├── middlewares/            # Auth middleware
│   ├── routes/                 # API & web routes
│   ├── services/               # Business logic
│   └── templates/              # Jinja2 templates
├── static/
│   ├── css/style.css          # CSS variables & global styles  
│   └── js/components/         # UID-based Lit.js components
├── uploads/                   # File storage (dev)
├── database.db               # SQLite database (dev)
└── .env                      # Environment config

🚀 Quick Start

1. Setup Project

mkdir my-flash-feather-app && cd my-flash-feather-app
python -m venv venv
source venv/bin/activate  # or venv\Scripts\activate on Windows

2. Install Dependencies

pip install fastapi uvicorn[standard] sqlalchemy jinja2 python-dotenv pyjwt passlib[bcrypt] authlib httpx
pip freeze > requirements.txt

3. Environment Configuration

Create .env:

APP_NAME=my-app
ENVIRONMENT=development
JWT_SECRET=your_super_secret_jwt_key_change_in_production
ACCESS_TOKEN_EXPIRE_SECONDS=900
REFRESH_TOKEN_EXPIRE_SECONDS=604800

# Optional: Google OAuth
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret

4. Run Application

python -m app.main

Visit http://localhost:8000 - Admin account auto-created:

• Email: admin@flashfeather.com
• Password: 123456

🆔 UID Component System

The Secret Sauce: Unique component identifiers prevent CSS conflicts.

Component Naming Pattern

• File: {component_name}_cc{XX}.js (e.g., login_form_cc02.js)
• CSS Classes: .cc{XX}-{class-name} (e.g., .cc02-form)
• HTML IDs: cc{XX}-{element-name} (e.g., cc02-email)

Example Component Structure

// static/js/components/auth/login_form_cc02.js
class LoginForm extends LitElement {
  render() {
    return html`
      <form class="cc02-form">
        <input id="cc02-email" class="cc02-input" />
        <button class="cc02-submit-btn">Login</button>
      </form>
      <style>
        .cc02-form { background: var(--bg); }
        .cc02-input { color: var(--text); }
        .cc02-submit-btn { background: var(--accent); }
      </style>
    `;
  }
}

Current UID Registry

UID	Component	File
cc01	App Header	app_header_cc01.js
cc02	Login Form	login_form_cc02.js
cc03	Register Form	register_form_cc03.js
cc04	Google Signin	google_signin_button_cc04.js

🎨 CSS Variables Theme System

All styling uses CSS variables for consistency and easy theming:

:root {
  /* Colors */
  --bg: #1a0f0a;
  --text: #f5f1eb;
  --accent: #d2691e;
  --success: #6b8e23;
  --error: #cd5c5c;
  
  /* Spacing */
  --space-sm: 0.5rem;
  --space-md: 1rem;
  --space-lg: 1.5rem;
  
  /* Components */
  --radius-md: 12px;
  --button-padding-y: 0.875rem;
  --transition-normal: 0.25s ease;
}

🌍 Environment-Aware Deployment

Development:

• Database: ./database.db
• Uploads: ./uploads/

Production:

• Database: /var/www/{APP_NAME}-data/database.db
• Uploads: /var/www/{APP_NAME}-data/uploads/

No manual configuration needed - automatically detects environment!

📋 Core Principles

1. LLM-Friendly Patterns: Use stable APIs and well-documented libraries
2. Schema-Free APIs: Direct await request.json() without separate schemas
3. Component Isolation: UID system prevents CSS/JS conflicts
4. CSS Variables: Consistent theming without hardcoded values
5. Environment Awareness: Auto-configures for dev/production
6. Zero Dependencies Conflicts: Carefully chosen non-conflicting stack

🤝 Contributing

This project needs you! The original creator has moved on to other projects.

How to Contribute

1. Fork the repository
2. Pick an enhancement from issues or propose your own
3. Follow the UID system for new components (cc05, cc06...)
4. Use CSS variables for all styling
5. Keep LLM-friendliness in mind

Potential Improvements

• Additional UI components with UID system
• Database adapters (PostgreSQL, MongoDB)
• Enhanced authentication providers
• CLI tool for project scaffolding
• Component generator following UID patterns
• Performance optimizations
• Testing framework integration

📄 License

MIT License - feel free to use in your projects!

🆘 Support & Community

• Issues: GitHub Issues
• Discussions: Share ideas and get help
• Wiki: Community-maintained documentation

---

Made for developers building with AI assistance 🤖✨