Rustelo/docs/admin-dashboard.md

Admin Dashboard System

A comprehensive admin dashboard built on top of the existing Rustelo authentication and content management infrastructure.

🚀 Features

✅ User Management

• View, create, edit, and manage users
• Role assignment and permission management
• User status management (Active, Inactive, Suspended, Pending)
• Bulk user operations
• User activity tracking

✅ Role-Based Access Control (RBAC)

• Create and manage custom roles
• Assign granular permissions
• Hierarchical role inheritance
• System role protection
• Permission auditing

✅ Content Management

• Multi-source content support (Database + Files)
• Content types: Blog, Page, Article, Documentation, Tutorial
• Content formats: Markdown, HTML, Plain Text
• Content states: Draft, Published, Archived, Scheduled
• SEO metadata management
• File upload capabilities
• Content analytics and view tracking

✅ Internationalization

• Full i18n support (English/Spanish)
• Localized admin interface
• Easy to extend with additional languages

✅ Database Abstraction

• Works with PostgreSQL and SQLite
• Automatic database type detection
• Unified query interface

📁 Project Structure

template/client/src/
├── components/admin/           # Admin-specific components
│   ├── AdminLayout.rs         # Main admin layout with navigation
│   └── mod.rs
├── pages/admin/               # Admin page components
│   ├── Dashboard.rs           # Admin dashboard with stats
│   ├── Users.rs               # User management
│   ├── Roles.rs               # Role management
│   ├── Content.rs             # Content management
│   └── mod.rs
└── examples/
    └── admin_integration.rs   # Integration examples

template/server/src/
├── auth/                      # Authentication system
│   ├── rbac_service.rs        # RBAC implementation
│   ├── middleware.rs          # Auth middleware
│   └── routes.rs              # Auth routes
├── content/                   # Content management
│   ├── service.rs             # Content service
│   ├── repository.rs          # Data access
│   ├── file_loader.rs         # File-based content
│   └── routes.rs              # Content API routes
└── database/                  # Database abstraction
    ├── mod.rs                 # Database pool management
    ├── auth.rs                # Auth-related queries
    └── rbac.rs                # RBAC queries

template/shared/src/
├── auth.rs                    # Shared auth types
└── content.rs                 # Shared content types

template/content/
└── texts.toml                 # i18n translations

🛠️ Setup

1. Enable Required Features

In your Cargo.toml:

[features]
default = ["auth", "content-db", "rbac"]
auth = ["dep:jsonwebtoken", "dep:argon2"]
content-db = ["dep:pulldown-cmark", "dep:syntect"]
rbac = ["dep:serde_json"]

2. Database Setup

The admin dashboard works with your existing database. Ensure migrations are run:

# PostgreSQL
sqlx migrate run --database-url postgresql://user:pass@localhost/db

# SQLite
sqlx migrate run --database-url sqlite:data/app.db

3. Environment Configuration

Add to your .env file:

# Database (choose one)
DATABASE_URL=postgresql://user:pass@localhost/db
# DATABASE_URL=sqlite:data/app.db

# Authentication
JWT_SECRET=your-super-secret-jwt-key
JWT_EXPIRATION_HOURS=24

# Content Management
CONTENT_SOURCE=both  # database, files, or both
CONTENT_DIR=./content

4. Admin User Setup

Create an initial admin user:

# Using the existing auth system
cargo run --bin create-admin-user

Or via API:

curl -X POST http://localhost:3030/api/auth/register \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@yourapp.com",
    "password": "secure-password",
    "roles": ["admin"]
  }'

🔗 Integration

Router Integration

Add admin routes to your main app:

use crate::components::admin::AdminLayout;
use leptos_router::*;

#[component]
pub fn App() -> impl IntoView {
    view! {
        <Router>
            <Routes>
                // Public routes
                <Route path="/" view=HomePage />
                <Route path="/about" view=AboutPage />
                
                // Protected admin routes
                <Route path="/admin/*" view=AdminLayout />
            </Routes>
        </Router>
    }
}

Navigation Integration

Add admin link to your navigation:

use crate::auth::use_auth;

#[component]
pub fn Navigation() -> impl IntoView {
    let auth = use_auth();
    
    view! {
        <nav>
            <a href="/">Home</a>
            <a href="/about">About</a>
            
            // Admin link - only for admin users
            <Show when=move || auth.has_role("admin")>
                <a href="/admin">Admin Dashboard</a>
            </Show>
        </nav>
    }
}

Authentication Guard

Protect admin routes with authentication:

#[component]
pub fn ProtectedAdminRoute() -> impl IntoView {
    let auth = use_auth();
    
    view! {
        <Show
            when=move || auth.is_authenticated() && auth.has_role("admin")
            fallback=|| view! { <div>"Access Denied"</div> }
        >
            <AdminLayout />
        </Show>
    }
}

🎨 Customization

Styling

The admin dashboard uses Tailwind CSS classes. Customize the appearance by:

1. Override CSS classes in your components
2. Extend Tailwind config for custom colors/spacing
3. Create custom admin themes by modifying the AdminLayout component

Adding New Admin Pages

1. Create a new component in pages/admin/:

// pages/admin/Analytics.rs
#[component]
pub fn AdminAnalytics() -> impl IntoView {
    let i18n = use_i18n();
    
    view! {
        <div class="min-h-screen bg-gray-50">
            <div class="py-6">
                <div class="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
                    <h1 class="text-3xl font-bold text-gray-900">
                        {move || i18n.t("admin.analytics.title")}
                    </h1>
                    // Your analytics content here
                </div>
            </div>
        </div>
    }
}

2. Add the route to AdminLayout:

// In AdminLayout.rs
<Routes>
    <Route path="/admin" view=AdminDashboard />
    <Route path="/admin/users" view=AdminUsers />
    <Route path="/admin/roles" view=AdminRoles />
    <Route path="/admin/content" view=AdminContent />
    <Route path="/admin/analytics" view=AdminAnalytics />  // New route
</Routes>

3. Add navigation item:

// In AdminLayout.rs navigation
<AdminNavItem
    section=AdminSection::Analytics
    current_section=current_section
    i18n=i18n.clone()
/>

Adding Translations

Add new translations to content/texts.toml:

[en]
"admin.analytics.title" = "Analytics Dashboard"
"admin.analytics.subtitle" = "View application metrics and insights"

[es]
"admin.analytics.title" = "Panel de Analíticas"
"admin.analytics.subtitle" = "Ver métricas y conocimientos de la aplicación"

🔒 Security

Authentication

• JWT-based authentication
• Secure password hashing with Argon2
• Session management
• OAuth2 integration (Google, GitHub)
• Two-factor authentication (2FA/TOTP)

Authorization

• Role-based access control (RBAC)
• Granular permissions
• Route-level protection
• API endpoint protection
• Hierarchical roles

Best Practices

1. Always verify admin role before showing admin UI
2. Protect API endpoints with RBAC middleware
3. Use HTTPS in production
4. Implement rate limiting for admin actions
5. Audit admin activities for security compliance

📊 Content Management

Content Sources

The system supports multiple content sources:

• Database: Dynamic content stored in PostgreSQL/SQLite
• Files: Static content from markdown/HTML files
• Both: Hybrid approach combining database and file content

Content Types

• Blog: Blog posts and articles
• Page: Static pages
• Article: Long-form content
• Documentation: Technical documentation
• Tutorial: Step-by-step guides
• Custom: User-defined content types

Content Workflow

1. Create: Content starts as a draft
2. Edit: Authors can modify content
3. Review: Optional review process
4. Publish: Make content live
5. Schedule: Publish at a specific time
6. Archive: Remove from public view

File Upload

Support for various file types:

• Markdown (.md, .markdown)
• HTML (.html)
• Text (.txt)
• Images (for featured images)
• Documents (PDFs, etc.)

🌐 API Endpoints

Authentication

• POST /api/auth/login - User login
• POST /api/auth/logout - User logout
• GET /api/auth/me - Get current user
• POST /api/auth/refresh - Refresh token

User Management

• GET /api/admin/users - List users
• POST /api/admin/users - Create user
• PUT /api/admin/users/:id - Update user
• DELETE /api/admin/users/:id - Delete user

Role Management

• GET /api/admin/roles - List roles
• POST /api/admin/roles - Create role
• PUT /api/admin/roles/:id - Update role
• DELETE /api/admin/roles/:id - Delete role

Content Management

• GET /api/admin/content - List content
• POST /api/admin/content - Create content
• PUT /api/admin/content/:id - Update content
• DELETE /api/admin/content/:id - Delete content
• POST /api/admin/content/upload - Upload files

Analytics

• GET /api/admin/stats - Dashboard statistics
• GET /api/admin/analytics - Detailed analytics

🧪 Testing

Unit Tests

# Test admin components
cargo test admin --features "auth,content-db,rbac"

# Test specific functionality
cargo test auth::rbac::tests
cargo test content::service::tests

Integration Tests

# Test full admin workflow
cargo test integration::admin --features "auth,content-db,rbac"

End-to-End Tests

# Run with headless browser
cargo test e2e::admin_dashboard

🚀 Deployment

Production Build

# Build with all admin features
cargo build --release --features "tls,auth,content-db,rbac"

Docker Deployment

FROM rust:1.75 as builder
WORKDIR /app
COPY . .
RUN cargo build --release --features "tls,auth,content-db,rbac"

FROM debian:bookworm-slim
RUN apt-get update && apt-get install -y ca-certificates
COPY --from=builder /app/target/release/server /usr/local/bin/
COPY --from=builder /app/content /app/content
EXPOSE 3030
CMD ["server"]

Environment Variables

# Production configuration
DATABASE_URL=postgresql://user:pass@db:5432/production_db
JWT_SECRET=super-secure-production-secret
RUST_LOG=info
ENVIRONMENT=production

# TLS configuration
TLS_CERT_PATH=/etc/ssl/certs/app.crt
TLS_KEY_PATH=/etc/ssl/private/app.key

# Admin settings
ADMIN_EMAIL=admin@yourcompany.com
ADMIN_REGISTRATION_ENABLED=false

📈 Performance

Optimization Tips

1. Database Indexing: Ensure proper indexes on user/content tables
2. Caching: Enable content caching for better performance
3. Pagination: Use pagination for large datasets
4. Lazy Loading: Load admin components only when needed
5. Bundle Optimization: Split admin code into separate bundles

Monitoring

• Database queries: Monitor slow queries
• Memory usage: Track memory consumption
• Response times: Monitor API response times
• Error rates: Track error rates and patterns

🔧 Troubleshooting

Common Issues

Admin dashboard not loading

• Check authentication state
• Verify admin role assignment
• Check browser console for errors

Permission denied errors

• Verify user has admin role
• Check RBAC configuration
• Review middleware setup

Content not displaying

• Check content source configuration
• Verify database connection
• Check file permissions for file-based content

Database connection issues

• Verify DATABASE_URL format
• Check database connectivity
• Review migration status

Debug Mode

Enable debug logging:

RUST_LOG=debug cargo run

Check specific modules:

RUST_LOG=rustelo::auth=debug,rustelo::content=debug cargo run

🤝 Contributing

Adding Features

1. Follow the existing architecture patterns
2. Add comprehensive tests
3. Update documentation
4. Add i18n translations
5. Ensure accessibility compliance

Code Style

• Use rustfmt for formatting
• Follow Rust naming conventions
• Add documentation comments
• Write descriptive commit messages

Pull Request Process

1. Create feature branch
2. Implement changes with tests
3. Update documentation
4. Submit PR with description
5. Address review feedback

📄 License

This admin dashboard system is part of the Rustelo framework and is licensed under the MIT License.

🆘 Support

• Documentation: Full Documentation
• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Examples: See examples/admin_integration.rs for complete integration examples

---

Built with ❤️ using Rust, Leptos, and modern web technologies.