ai-flow-dev 1.0.1

package/templates/fullstack/specs/configuration.template.md

@@ -0,0 +1,380 @@
+# Configuration Specifications
+
+> Environment variables and configuration management for {{PROJECT_NAME}} (Full Stack)
+
+---
+
+## 🎯 Configuration Strategy
+
+**Approach:** {{CONFIGURATION_APPROACH}}
+
+**Key Principles:**
+1. **Separation of Concerns** - Backend vs Frontend config
+2. **Security First** - Never expose secrets to client
+3. **Type Safety** - Validate and type all config
+4. **Environment Parity** - Consistent config across environments
+
+---
+
+## 📁 Configuration Files Structure
+
+```
+{{PROJECT_NAME}}/
+├── backend/
+│   ├── .env.local              # Local overrides (gitignored)
+│   ├── .env.development        # Development defaults
+│   ├── .env.production          # Production defaults
+│   └── .env.example            # Template for new developers
+├── frontend/
+│   ├── .env.local              # Local overrides (gitignored)
+│   ├── .env.development        # Development defaults
+│   ├── .env.production          # Production defaults
+│   ├── .env.example            # Template for new developers
+│   └── src/
+│       └── config/
+│           ├── index.ts        # Configuration loader
+│           ├── schema.ts       # Validation schema
+│           └── constants.ts    # Static constants
+```
+
+---
+
+## 🔐 Backend Environment Variables
+
+### Required Variables
+
+{{#EACH BACKEND_REQUIRED_VAR}}
+#### `{{VAR_NAME}}`
+
+**Description:** {{VAR_DESCRIPTION}}
+
+**Type:** {{VAR_TYPE}}
+
+**Example:** `{{VAR_EXAMPLE}}`
+
+{{#IF VAR_VALIDATION}}**Validation:** {{VAR_VALIDATION}}{{/IF}}
+
+{{/EACH}}
+
+### Optional Variables
+
+{{#EACH BACKEND_OPTIONAL_VAR}}
+#### `{{VAR_NAME}}`
+
+**Description:** {{VAR_DESCRIPTION}}
+
+**Type:** {{VAR_TYPE}}
+
+**Default:** `{{VAR_DEFAULT}}`
+
+**Example:** `{{VAR_EXAMPLE}}`
+
+{{/EACH}}
+
+---
+
+## 🎨 Frontend Environment Variables
+
+### Required Variables
+
+**Format:** `VITE_[CATEGORY]_[NAME]` (or your build tool's prefix)
+
+{{#EACH FRONTEND_REQUIRED_VAR}}
+#### `{{VAR_NAME}}`
+
+**Description:** {{VAR_DESCRIPTION}}
+
+**Type:** {{VAR_TYPE}}
+
+**Example:** `{{VAR_EXAMPLE}}`
+
+{{#IF VAR_VALIDATION}}**Validation:** {{VAR_VALIDATION}}{{/IF}}
+
+{{/EACH}}
+
+### Optional Variables
+
+{{#EACH FRONTEND_OPTIONAL_VAR}}
+#### `{{VAR_NAME}}`
+
+**Description:** {{VAR_DESCRIPTION}}
+
+**Type:** {{VAR_TYPE}}
+
+**Default:** `{{VAR_DEFAULT}}`
+
+**Example:** `{{VAR_EXAMPLE}}`
+
+{{/EACH}}
+
+### Variable Naming Convention (Frontend)
+
+**Format:** `VITE_[CATEGORY]_[NAME]`
+
+**Categories:**
+- `VITE_APP_*` - Application metadata
+- `VITE_API_*` - API endpoints (points to backend)
+- `VITE_AUTH_*` - Authentication config
+- `VITE_FEATURE_*` - Feature flags
+- `VITE_ANALYTICS_*` - Analytics services
+
+**Important:** Only variables prefixed with `VITE_` (or your build tool's prefix) are exposed to the client.
+
+---
+
+## 🌍 Configuration by Environment
+
+### Development
+
+**Backend (.env.development):**
+```bash
+{{BACKEND_DEV_ENV_CONFIG}}
+```
+
+**Frontend (.env.development):**
+```bash
+{{FRONTEND_DEV_ENV_CONFIG}}
+```
+
+### Staging
+
+**Backend (.env.staging):**
+```bash
+{{BACKEND_STAGING_ENV_CONFIG}}
+```
+
+**Frontend (.env.staging):**
+```bash
+{{FRONTEND_STAGING_ENV_CONFIG}}
+```
+
+### Production
+
+**Backend (.env.production):**
+```bash
+{{BACKEND_PRODUCTION_ENV_CONFIG}}
+```
+
+**Frontend (.env.production):**
+```bash
+{{FRONTEND_PRODUCTION_ENV_CONFIG}}
+```
+
+---
+
+## 🔌 External Services
+
+### Backend Services
+
+{{#EACH BACKEND_EXTERNAL_SERVICE}}
+### {{SERVICE_NAME}}
+
+**Purpose:** {{SERVICE_PURPOSE}}
+
+**Configuration:**
+```bash
+{{SERVICE_ENV_VARS}}
+```
+
+**Documentation:** {{SERVICE_DOCS_URL}}
+
+{{#IF SERVICE_FALLBACK}}**Fallback:** {{SERVICE_FALLBACK}}{{/IF}}
+
+{{/EACH}}
+
+### Frontend Services
+
+{{#EACH FRONTEND_EXTERNAL_SERVICE}}
+### {{SERVICE_NAME}}
+
+**Purpose:** {{SERVICE_PURPOSE}}
+
+**Configuration:**
+```bash
+{{SERVICE_ENV_VARS}}
+```
+
+**Documentation:** {{SERVICE_DOCS_URL}}
+
+{{#IF SERVICE_FALLBACK}}**Fallback:** {{SERVICE_FALLBACK}}{{/IF}}
+
+{{/EACH}}
+
+---
+
+## 💾 Database Configuration (Backend)
+
+```bash
+{{DATABASE_CONFIG}}
+```
+
+**Connection Pool:**
+- Min: {{DB_POOL_MIN}}
+- Max: {{DB_POOL_MAX}}
+- Idle Timeout: {{DB_IDLE_TIMEOUT}}ms
+
+---
+
+## 🔐 Secrets Management
+
+### Backend Secrets
+
+**Never commit these variables:**
+
+{{#EACH BACKEND_SECRET_VAR}}
+- `{{VAR_NAME}}` - {{VAR_PURPOSE}}
+{{/EACH}}
+
+**Storage:** {{BACKEND_SECRETS_STORAGE}}
+
+### Frontend Secrets
+
+**Important:** Frontend should NEVER contain secrets. Only public keys and non-sensitive configuration.
+
+**Allowed:**
+- Public API keys (e.g., Google Maps API key)
+- Public service IDs
+- Feature flags
+- Analytics IDs
+
+**Never:**
+- Database credentials
+- API secret keys
+- Authentication secrets
+- Private keys
+
+---
+
+## 🚩 Feature Flags
+
+### Backend Feature Flags
+
+{{#IF BACKEND_FEATURE_FLAGS}}
+{{#EACH BACKEND_FEATURE_FLAG}}
+### `{{FLAG_NAME}}`
+
+**Description:** {{FLAG_DESCRIPTION}}
+
+**Default:** {{FLAG_DEFAULT}}
+
+**Environments:** {{FLAG_ENVIRONMENTS}}
+
+{{/EACH}}
+
+{{ELSE}}
+Backend feature flags not implemented yet.
+
+{{/IF}}
+
+### Frontend Feature Flags
+
+{{#IF FRONTEND_FEATURE_FLAGS}}
+{{#EACH FRONTEND_FEATURE_FLAG}}
+### `{{FLAG_NAME}}`
+
+**Description:** {{FLAG_DESCRIPTION}}
+
+**Default:** {{FLAG_DEFAULT}}
+
+**Environments:** {{FLAG_ENVIRONMENTS}}
+
+{{/EACH}}
+
+{{ELSE}}
+Frontend feature flags not implemented yet.
+
+{{/IF}}
+
+---
+
+## 🔒 Security Best Practices
+
+### Backend
+
+- ✅ Store all secrets in environment variables
+- ✅ Use secrets manager for production (AWS Secrets Manager, Azure Key Vault, etc.)
+- ✅ Never log secrets or sensitive data
+- ✅ Rotate secrets regularly
+- ✅ Use different secrets per environment
+
+### Frontend
+
+- ✅ Never expose secrets to client code
+- ✅ Only use public keys and non-sensitive config
+- ✅ Sanitize error messages (don't expose config in production)
+- ✅ Validate all environment variables
+- ✅ Use Content Security Policy headers
+
+### Example: API Key Management
+
+```bash
+# ❌ WRONG - Secret key in frontend
+VITE_STRIPE_SECRET_KEY=sk_live_...
+
+# ✅ CORRECT - Public key in frontend, secret in backend
+# Frontend
+VITE_STRIPE_PUBLISHABLE_KEY=pk_live_...
+
+# Backend
+STRIPE_SECRET_KEY=sk_live_...
+```
+
+---
+
+## 🧪 Testing Configuration
+
+### Backend Test Environment
+
+```bash
+# .env.test
+NODE_ENV=test
+DATABASE_URL=postgresql://test:test@localhost:5432/test_db
+LOG_LEVEL=silent
+```
+
+### Frontend Test Environment
+
+```typescript
+// vitest.config.ts
+export default defineConfig({
+  test: {
+    env: {
+      VITE_API_BASE_URL: 'http://localhost:3001/api',
+      VITE_APP_ENV: 'test',
+    },
+  },
+});
+```
+
+---
+
+## 📊 Configuration Monitoring
+
+### Backend
+
+- Log configuration on startup (development only)
+- Monitor secret rotation
+- Track configuration changes
+
+### Frontend
+
+- Log config on startup (development only)
+- Monitor API endpoint availability
+- Track feature flag usage
+
+---
+
+## 🔗 Related Documents
+
+- [AI Instructions](../ai-instructions.md) - Configuration rules
+- [Security Specification](security.md) - Security requirements
+- [Deployment Guide](../docs/operations.md) - Environment setup
+
+---
+
+**Document Version:** 1.0
+
+**Last Updated:** {{GENERATION_DATE}}
+
+**Generated by:** AI Flow v1.3.0
+

package/templates/mobile/AGENT.template.md

@@ -0,0 +1,251 @@
+# AGENT.md
+
+> Universal AI Assistant Configuration
+>
+> This file provides context for ALL AI development tools (Claude, Copilot, Cursor, Gemini, etc.)
+
+---
+
+## 📋 About This Project
+
+**Project Name:** {{PROJECT_NAME}}
+
+**Description:** {{PROJECT_DESCRIPTION}}
+
+**Problem We're Solving:** {{PROBLEM_STATEMENT}}
+
+**Target Users:** {{TARGET_USERS}}
+
+### Technical Context
+
+**Project Type:** Backend API/Service
+**Architecture:** {{ARCHITECTURE_PATTERN}}
+**Primary Language:** {{LANGUAGE}} {{LANGUAGE_VERSION}}
+**Framework:** {{FRAMEWORK}}
+**Database:** {{DATABASE}} with {{ORM}}
+
+**Key Characteristics:**
+- Authentication: {{AUTH_METHOD}}
+- API Style: {{API_STYLE}}
+- Deployment: {{DEPLOYMENT_PLATFORM}}
+- Current Phase: {{PROJECT_PHASE}}
+
+> This project uses AI-assisted development with comprehensive documentation.
+> All files below provide context to AI assistants for consistent, high-quality code generation.
+
+---
+
+## 🏗️ Documentation Architecture
+
+This project follows **AI-assisted development** with comprehensive documentation.
+All documentation is structured to guide AI assistants in understanding the project deeply.
+
+### 📚 Core Documentation (Read in Order)
+
+1. **`ai-instructions.md`** ⭐ **START HERE**
+
+   - Tech stack and versions
+   - NEVER/ALWAYS rules
+   - Development workflow
+   - Priorities
+
+2. **`project-brief.md`**
+
+   - Business context
+   - Objectives and scope
+   - Constraints and success metrics
+
+3. **`README.md`**
+
+   - Quick start
+   - Installation and commands
+   - Project directory tour
+
+4. **`docs/architecture.md`**
+
+   - System architecture pattern
+   - Component structure
+   - Request/response flow
+
+5. **`docs/data-model.md`**
+
+   - Database schema
+   - Entity relationships
+   - Data patterns
+
+6. **`docs/code-standards.md`**
+
+   - Naming conventions
+   - Code quality rules
+   - Error handling patterns
+
+7. **`docs/testing.md`**
+
+   - Testing strategy
+   - Coverage requirements
+   - Test patterns
+
+8. **`docs/operations.md`**
+
+   - Deployment procedures
+   - Monitoring and alerts
+   - Scaling strategy
+
+9. **`docs/business-flows.md`**
+
+   - End-to-end business processes
+   - Key actors and systems
+   - Flow diagrams
+
+10. **`docs/api.md`**
+
+    - Endpoint conventions
+    - Authentication and pagination rules
+    - Request/response examples
+
+11. **`docs/contributing.md`**
+
+    - Development setup
+    - Contribution guidelines
+    - Code review process
+
+12. **`specs/security.md`**
+
+    - Authentication/Authorization
+    - Security policies
+    - Compliance requirements
+
+13. **`specs/configuration.md`**
+
+    - Environment variables
+    - External services
+    - Configuration by environment
+
+14. **`.env.example`**
+    - Required environment variables
+    - Default/local values
+    - Secrets handling guidance
+
+---
+
+## ⚡ Quick Reference
+
+### Tech Stack
+
+**Backend:**
+
+- Framework: {{FRAMEWORK}}
+- Language: {{LANGUAGE}} {{LANGUAGE_VERSION}}
+- Database: {{DATABASE}}
+- ORM: {{ORM}}
+- Authentication: {{AUTH_METHOD}}
+- Caching: {{CACHE_STRATEGY}}
+
+**Infrastructure:**
+
+- Deployment: {{DEPLOYMENT_PLATFORM}}
+- CI/CD: {{CICD_PLATFORM}}
+- Monitoring: {{MONITORING_TOOLS}}
+
+### Critical Rules
+
+**❌ NEVER:**
+{{NEVER_RULES}}
+
+**✅ ALWAYS:**
+{{ALWAYS_RULES}}
+
+---
+
+## 🤖 AI Assistant Workflow
+
+When working on this project:
+
+1. **Before starting ANY task:**
+
+   - Read `ai-instructions.md` for project-wide rules
+   - Check relevant documentation for the area you're working on
+   - Understand the business context from `project-brief.md`
+
+2. **When implementing features:**
+
+   - Follow architecture patterns from `docs/architecture.md`
+   - Respect data models from `docs/data-model.md`
+   - Apply code standards from `docs/code-standards.md`
+   - Add tests according to `docs/testing.md`
+
+3. **When handling security:**
+
+   - Consult `specs/security.md` for auth/authz
+   - Never hardcode secrets (use `specs/configuration.md`)
+   - Follow security headers and encryption requirements
+
+4. **When deploying:**
+   - Follow procedures in `docs/operations.md`
+   - Update configuration per environment
+   - Check health endpoints
+
+---
+
+## 🛠️ Tool-Specific Configurations
+
+Different AI tools have specific configuration files that extend this AGENT.md:
+
+### Claude Code
+
+- **File:** `.clauderules`
+- **Purpose:** Claude-specific instructions and preferences
+- **References:** This AGENT.md + project docs
+
+### Cursor
+
+- **File:** `.cursorrules`
+- **Purpose:** Cursor-specific context and rules
+- **References:** This AGENT.md + project docs
+
+### GitHub Copilot
+
+- **File:** `.github/copilot-instructions.md`
+- **Purpose:** Copilot workspace instructions
+- **References:** This AGENT.md + project docs
+
+**All tool-specific configs reference this AGENT.md as the source of truth.**
+
+---
+
+## 📊 Project Status
+
+**Current Phase:** {{PROJECT_PHASE}}
+
+**Architecture:** {{ARCHITECTURE_PATTERN}}
+
+**Compliance:** {{COMPLIANCE_REQUIREMENTS}}
+
+---
+
+## 🚀 Getting Started
+
+### For AI Assistants
+
+1. Read this AGENT.md completely
+2. Read `ai-instructions.md` for critical rules
+3. Familiarize with `docs/architecture.md`
+4. Review `docs/code-standards.md` for coding patterns
+5. Check `specs/security.md` before handling auth/sensitive data
+
+### For Developers
+
+See `README.md` for installation and setup instructions.
+
+---
+
+## 📝 Document Update Policy
+
+- Documents are **living artifacts** - update as project evolves
+- Breaking changes to architecture → Update `docs/architecture.md`
+- New security requirements → Update `specs/security.md`
+- Stack changes → Update `ai-instructions.md` AND this AGENT.md
+
+**Last Updated:** {{GENERATION_DATE}}
+
+**Generated by:** AI Flow v1.0.8