8.6 KiB

Raw Blame History

MonacoUSA Portal - Cline Workspace Rules

Project Overview

This is the MonacoUSA Portal - a modern, responsive web portal built with Nuxt 3, Vuetify 3, and Keycloak authentication. The portal provides a unified dashboard for tools and services with mobile-first design and PWA capabilities.

Tech Stack & Architecture

Core Technologies

Framework: Nuxt 3 with Vue 3 (SPA mode)
UI Library: Vuetify 3 with MonacoUSA theme (#a31515 primary color)
Authentication: Keycloak (OAuth2/OIDC)
Database: NocoDB (API-first database)
File Storage: MinIO (S3-compatible object storage)
PWA: Vite PWA plugin with offline support
TypeScript: Full TypeScript support throughout

Project Structure

monacousa-portal/
├── components/          # Vue components
├── composables/         # Vue composables (useAuth, etc.)
├── layouts/            # Nuxt layouts (dashboard layout)
├── middleware/         # Route middleware (auth middleware)
├── pages/              # Application pages
│   ├── auth/           # Authentication pages
│   └── dashboard/      # Dashboard pages
├── plugins/            # Nuxt plugins
├── public/             # Static assets
├── server/             # Server-side code
│   ├── api/            # API routes
│   ├── utils/          # Server utilities
│   └── plugins/        # Server plugins
├── utils/              # Shared utilities
└── docs/               # Documentation

Development Guidelines

1. Authentication System

Uses Keycloak OAuth2/OIDC flow
Session management with encrypted cookies
useAuth() composable for authentication state
Middleware protection for authenticated routes
Support for user groups/roles (admin, manager, etc.)

2. API Structure

RESTful APIs in server/api/
Database operations via NocoDB client
File operations via MinIO client
Consistent error handling and responses
Health check endpoint at /api/health

3. UI/UX Standards

Mobile-first responsive design
Vuetify 3 components with MonacoUSA theme
Dashboard layout with collapsible sidebar
PWA support with install prompts
Consistent color scheme: #a31515 (primary), #ffffff (secondary)

4. File Organization

Components in components/ directory
Composables for reusable logic
Server utilities in server/utils/
TypeScript types in utils/types.ts
Environment configuration in .env files

Coding Standards

1. Vue/Nuxt Patterns

// Use composition API with <script setup>
<script setup lang="ts">
definePageMeta({
  layout: 'dashboard',
  middleware: 'auth'
});

const { user, isAdmin } = useAuth();
</script>

2. API Route Patterns

// server/api/example.ts
export default defineEventHandler(async (event) => {
  try {
    // Implementation
    return { success: true, data: result };
  } catch (error) {
    throw createError({
      statusCode: 500,
      statusMessage: 'Operation failed'
    });
  }
});

3. Database Operations

// Use NocoDB client
const nocodb = createNocoDBClient();
const records = await nocodb.findAll('tableName', { limit: 10 });

4. File Storage

// Use MinIO client
const minio = createMinIOClient();
await minio.uploadFile(fileName, buffer, contentType);

Environment Configuration

Required Environment Variables

# Keycloak Configuration
NUXT_KEYCLOAK_ISSUER=https://auth.monacousa.org/realms/monacousa-portal
NUXT_KEYCLOAK_CLIENT_ID=monacousa-portal
NUXT_KEYCLOAK_CLIENT_SECRET=your-keycloak-client-secret
NUXT_KEYCLOAK_CALLBACK_URL=https://monacousa.org/auth/callback

# NocoDB Configuration
NUXT_NOCODB_URL=https://db.monacousa.org
NUXT_NOCODB_TOKEN=your-nocodb-token
NUXT_NOCODB_BASE_ID=your-nocodb-base-id

# MinIO Configuration
NUXT_MINIO_ENDPOINT=s3.monacousa.org
NUXT_MINIO_PORT=443
NUXT_MINIO_USE_SSL=true
NUXT_MINIO_ACCESS_KEY=your-minio-access-key
NUXT_MINIO_SECRET_KEY=your-minio-secret-key
NUXT_MINIO_BUCKET_NAME=monacousa-portal

# Security Configuration
NUXT_SESSION_SECRET=your-48-character-session-secret-key-here
NUXT_ENCRYPTION_KEY=your-32-character-encryption-key-here

# Public Configuration
NUXT_PUBLIC_DOMAIN=monacousa.org

Key Features & Capabilities

1. Authentication Flow

OAuth2/OIDC with Keycloak
Secure session management
Role-based access control
Automatic token refresh
Logout functionality

2. Dashboard System

Responsive sidebar navigation
Role-based menu items
PWA install prompts
Mobile-optimized layout
User profile display

3. File Management

Upload/download via MinIO
File type validation
Progress indicators
Error handling
Secure file access

4. Database Integration

CRUD operations via NocoDB
Dynamic table access
Query parameters support
Error handling
Type safety

5. PWA Features

Offline support
Install prompts
Service worker
App manifest
Mobile optimization

Development Commands

# Development
npm run dev

# Build for production
npm run build

# Preview production build
npm run preview

# Type checking
npm run typecheck

Testing & Health Checks

Health Check Endpoint

GET /api/health - System health status
Checks database, storage, and auth connectivity
Returns status: healthy/degraded/unhealthy

Manual Testing

Authentication flow (login/logout)
Dashboard navigation
File upload/download
Database operations
Mobile responsiveness
PWA installation

Security Considerations

1. Session Security

Encrypted session cookies
Secure cookie settings
HTTPS required in production
Session timeout handling

2. API Security

Authentication middleware
Input validation
Error message sanitization
CORS configuration

3. File Security

File type validation
Size limits
Secure storage
Access control

Deployment Guidelines

1. Production Requirements

Node.js 18+
SSL certificate
Reverse proxy (nginx)
Environment variables configured

2. Build Process

npm ci --only=production
npm run build
npm run preview

3. Health Monitoring

Monitor /api/health endpoint
Check service dependencies
Monitor error logs
Performance metrics

Extension Guidelines

Adding New Tools

Create page in pages/dashboard/
Add navigation item to dashboard layout
Implement API routes if needed
Add database tables in NocoDB
Update TypeScript types
Test authentication and permissions

Adding New APIs

Create route in server/api/
Implement proper error handling
Add authentication if required
Update TypeScript types
Test with health checks

Adding New Components

Create in components/ directory
Follow Vuetify patterns
Ensure mobile responsiveness
Add proper TypeScript types
Test across devices

Troubleshooting

Common Issues

Authentication failures: Check Keycloak configuration
Database errors: Verify NocoDB connection and tokens
File upload issues: Check MinIO configuration and permissions
Build errors: Verify all environment variables are set
Mobile issues: Test responsive design and PWA features

Debug Tools

Browser developer tools
Network tab for API calls
Console for JavaScript errors
Health check endpoint
Server logs

Best Practices

1. Code Quality

Use TypeScript throughout
Follow Vue 3 composition API patterns
Implement proper error handling
Write descriptive commit messages
Keep components focused and reusable

2. Performance

Lazy load components where appropriate
Optimize images and assets
Use proper caching strategies
Monitor bundle size
Implement proper loading states

3. Security

Validate all inputs
Use HTTPS in production
Keep dependencies updated
Follow OWASP guidelines
Regular security audits

4. Maintainability

Document complex logic
Use consistent naming conventions
Keep functions small and focused
Separate concerns properly
Regular code reviews

Support & Resources

Documentation

Implementation guide: MONACOUSA_PORTAL_IMPLEMENTATION.md
Nuxt 3 documentation
Vuetify 3 documentation
Keycloak documentation
NocoDB API documentation

Key Files to Reference

nuxt.config.ts - Main configuration
server/utils/keycloak.ts - Authentication logic
composables/useAuth.ts - Auth composable
layouts/dashboard.vue - Main layout
utils/types.ts - TypeScript definitions

This workspace is designed to be a solid foundation for building custom tools and features while maintaining consistency, security, and performance standards.

8.6 KiB Raw Blame History