M.A.V.E.R.I.C.K.

Marvel AI-Vision Engine for Rapid Interactive Content Kreation

An advanced, AI-powered pre-production blueprint generator for the Marvel Universe.
Create character concepts, episode plots, visual styles, intelligence briefings, concept art, comic strips, and cinematic video shots with cutting-edge AI technology.

Features • Installation • Usage • Architecture • API Reference • Contributing

M.A.V.E.R.I.C.K. is a comprehensive pre-production tool designed for Marvel Universe content creators. Powered by Google's state-of-the-art Gemini 2.5 Flash AI model, Imagen 3.0 for image generation, and Veo 2.0 for video creation, this application streamlines the creative process by generating high-quality content across multiple mediums.

• 🎨 Multi-Modal Generation: Text, images, and videos - all in one platform
• 🧠 AI-Powered Creativity: Leverages cutting-edge Gemini AI technology
• 🎬 Production-Ready: Generates content suitable for professional pre-production workflows
• 💾 Export Capabilities: PDF, JSON, XML, FBX metadata, CSV, and Markdown formats
• 🎯 Marvel-Focused: Specialized prompts and data for authentic Marvel content
• ⚡ Real-Time Generation: Fast, responsive AI generation with progress tracking
• 🔐 User Authentication: Secure user accounts with session management
• 📁 Project Management: Organize and manage multiple projects
• 🚀 Batch Processing: Generate multiple items simultaneously
• 🔗 Content Sharing: Create shareable links for generated content
• 🦸 Marvel API Integration: Access official Marvel character data
• 🎭 Custom Characters: Build and manage your own character databases
• 🤝 Real-Time Collaboration: Live user presence and cross-tab content synchronization
• 👥 Team Management: Create teams, manage members, and set role-based permissions
• ☁️ Cloud Storage: Abstract cloud storage layer ready for backend integration

Create detailed character blueprints including:

• Creative character names
• Compelling 2-3 paragraph backstories
• Unique powers and abilities
• Meaningful weaknesses that create conflict
• Detailed visual descriptions for concept artists

Generate three distinct episode plot outlines featuring:

• Customizable hero and villain pairings
• 20 rich narrative themes to choose from
• Three-act story structures
• Catchy episode titles

Develop comprehensive style guides with:

• Overall aesthetic and mood descriptions
• Character design approaches
• Color palette guidelines
• Background and environment styling notes
• 8 preset visual styles for quick selection

Create SHIELD-style tactical dossiers including:

• Character aliases and identities
• Base of operations
• Abilities assessment
• Psychological profiles
• Exploitable weaknesses

Generate high-quality cinematic concept art:

• Dynamic action shots
• Character portraits
• Environment designs
• 1:1 aspect ratio JPEG output
• 30+ art styles to choose from

Create multi-panel comic strips with:

• 2-4 panel sequences
• 30 art styles (Classic, Manga, Noir, Cyberpunk, and more)
• Coherent visual storytelling
• Individual panel downloads

Produce short video shots featuring:

• High-definition quality
• Marvel movie-style cinematography
• Configurable generation timeout (up to 10 minutes)
• Progress tracking with themed messages
• MP4 format output

• Secure signup and login
• JWT-based session management
• Local storage persistence
• User profile management

• Create and organize projects
• Save multiple content items per project
• Export/import projects as JSON
• Track creation and update timestamps
• Tag-based organization

• Generate multiple characters, plots, styles, or intel simultaneously
• Real-time progress tracking
• Error handling for individual failures
• Queue management
• Configurable batch size and concurrency

• Create shareable links for any generated content
• Embedded content in URLs (no backend required)
• Copy to clipboard functionality
• View count tracking
• Shareable link management

• Search official Marvel characters
• Retrieve detailed character information
• Popular characters discovery
• Response caching for performance
• Seamless integration with generation workflows

• Create unlimited character databases
• Add heroes, villains, anti-heroes, and more
• Import/export databases as JSON
• Search and filter capabilities
• Tag-based organization
• Public/private database options

• PDF: Print-ready documents with formatted content
• JSON: Structured data for integration
• XML: Standardized data format
• FBX Metadata: 3D pipeline compatibility
• CSV: Tabular data for spreadsheets
• Markdown: Documentation-ready format

Collaborate with others using the BroadcastChannel API:

• Live user presence indicators (who is online and on which tab)
• Cross-tab content synchronization within the same browser
• Periodic heartbeats to detect offline collaborators
• Color-coded collaborator identities
• Extensible for multi-device collaboration via WebSocket or Firebase

Organize work with structured teams and role-based access control:

• Create and delete teams
• Invite and remove team members
• Assign roles: owner, editor, or viewer
• Role-based permission checks (canEdit, canManage)
• Associate projects with teams
• Persistent team data with localStorage

Abstract cloud storage layer with a promise-based API:

• Save and load arbitrary JSON documents with stable IDs
• Sync status tracking per item (synced, pending, error, local_only)
• Global sync-in-progress indicator
• Currently backed by localStorage; designed for easy replacement with Firebase, AWS S3, or a custom REST API

• Node.js (v18 or higher) - Download
• npm (comes with Node.js)
• Google Gemini API Key - Get one here
• Marvel API Keys (Optional) - Get them here for Marvel character integration

1. Clone the repository

   git clone https://github.com/GizzZmo/M.A.V.E.R.I.C.K.git
   cd M.A.V.E.R.I.C.K.

2. Install dependencies

   npm install

3. Configure API Keys

   Create a .env.local file in the project root:

   # Required: Google Gemini API Key
   API_KEY=your_gemini_api_key_here
   
   # Optional: Marvel API Keys (for character data integration)
   MARVEL_API_PUBLIC_KEY=your_marvel_public_key
   MARVEL_API_PRIVATE_KEY=your_marvel_private_key

4. Run the application

   npm run dev

5. Open in browser

   Navigate to http://localhost:3000

1. Navigate to the Character tab
2. Enter a core concept description in the text area
3. Click Generate
4. Review the generated character blueprint
5. Click Save Output to download as a text file

Example Input:

A tech-based hero from a futuristic Wakandan outpost who can manipulate sound waves

Example Output:

Name: Sonic Sage
Backstory: Born in the advanced technological hub of Wakanda's satellite city...
Powers: 
  - Sound wave manipulation for offense and defense
  - Sonic flight capabilities
  - Enhanced hearing and echolocation
Weaknesses:
  - Vulnerable in soundproof environments
  - Sensory overload from loud, chaotic noise

1. Navigate to the Plot tab
2. Select a Hero from the dropdown
3. Select a Villain from the dropdown
4. Choose a Theme
5. Click Generate to create three unique plot outlines

1. Navigate to the Style tab
2. Describe the desired visual style using keywords
3. Click Generate
4. Save the comprehensive style guide

1. Navigate to the Intel tab
2. Enter a character name
3. Click Generate to create a SHIELD-style dossier

1. Navigate to the Concept Art tab
2. Describe the scene or character you want to visualize
3. Click Generate (this may take 10-30 seconds)
4. Download the generated image

1. Navigate to the Comic Strip tab
2. Enter your story description
3. Select the number of panels (2-4)
4. Choose an art style
5. Click Generate to create all panels
6. Download individual panels as needed

1. Navigate to the Video Shot tab
2. Describe the cinematic shot you want
3. Click Generate
4. Wait for generation (typically 2-5 minutes)
5. Watch progress updates with Marvel-themed messages
6. Preview and download the video when complete

┌─────────────────────────────────────┐
│         Frontend Layer              │
│  Angular 20.1 + TypeScript 5.8      │
│  Signals for State Management       │
│  TailwindCSS for Styling            │
└─────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│        Service Layer                │
│  GeminiService (AI Integration)     │
│  AuthService (Authentication)       │
│  ProjectService (Organization)      │
│  BatchGenerationService (Queue)     │
│  ShareService (Sharing)             │
│  MarvelApiService (Marvel Data)     │
│  CustomCharacterService (DB)        │
│  ExportService (Multi-format)       │
│  ConfigService (Settings)           │
│  CollaborationService (Presence)    │
│  TeamService (Roles & Permissions)  │
│  CloudStorageService (Persistence)  │
│  Dependency Injection (Angular)     │
└─────────────────────────────────────┘
                  │
                  ▼
┌─────────────────────────────────────┐
│         AI Layer                    │
│  Google Gemini 2.5 Flash (Text)     │
│  Imagen 3.0 (Images)                │
│  Veo 2.0 (Videos)                   │
└─────────────────────────────────────┘

M.A.V.E.R.I.C.K./
├── src/
│   ├── app.component.ts          # Main component with UI logic
│   ├── app.component.html        # Application template
│   ├── services/
│   │   ├── gemini.service.ts     # AI integration service
│   │   ├── auth.service.ts       # User authentication & session management
│   │   ├── project.service.ts    # Project & content organization
│   │   ├── batch-generation.service.ts  # Batch AI generation
│   │   ├── share.service.ts      # Shareable link generation
│   │   ├── marvel-api.service.ts # Official Marvel API integration
│   │   ├── custom-character.service.ts  # Custom character databases
│   │   ├── export.service.ts     # Multi-format content export
│   │   ├── config.service.ts     # Centralized configuration
│   │   ├── collaboration.service.ts     # Real-time collaboration & presence
│   │   ├── team.service.ts       # Team management & role-based permissions
│   │   └── cloud-storage.service.ts     # Cloud storage abstraction layer
│   ├── models/
│   │   └── marvel-concept.model.ts  # TypeScript interfaces
│   └── data/
│       └── marvel-data.ts        # Marvel heroes, villains, themes
├── index.tsx                     # Application entry point
├── angular.json                  # Angular configuration
├── tsconfig.json                 # TypeScript configuration
├── CONTRIBUTING.md               # Contribution guidelines
├── SERVICES_GUIDE.md             # Services implementation guide
├── README.md                     # This file
└── package.json                  # Dependencies and scripts

The main application component that:

• Manages UI state with Angular Signals
• Handles user interactions
• Orchestrates AI generation workflows
• Provides download functionality

Core service for AI integration:

• Manages Google Gemini API client
• Provides type-safe generation methods
• Handles structured JSON responses
• Manages image and video generation
• Implements polling for async video operations

Type-safe interfaces for:

• Character concepts
• Plot outlines
• Visual style guides
• Intelligence briefings
• Video metadata

Generates a complete character blueprint.

Parameters:

• coreConcept (string): Core description of the character

Returns: Promise resolving to a RawCharacterConcept object

Example:

const character = await geminiService.generateCharacterConcept(
  "A hero who can control time"
);
console.log(character.name); // "Chronos Knight"

Creates three episode plot outlines.

Parameters:

• hero (string): Hero character name
• villain (string): Villain character name
• theme (string): Central narrative theme

Returns: Promise resolving to a RawPlotOutline object

Develops a visual style guide.

Parameters:

• keywords (string): Style description and keywords

Returns: Promise resolving to a RawVisualStyle object

Creates an intelligence briefing.

Parameters:

• characterName (string): Name of the character

Returns: Promise resolving to a RawCharacterIntel object

Generates concept art images.

Parameters:

• prompt (string): Image description

Returns: Promise resolving to an array of base64-encoded image URLs

Creates a multi-panel comic strip.

Parameters:

• story (string): Comic story description
• panels (number): Number of panels (2-4)
• style (string): Art style name

Returns: Promise resolving to an array of base64-encoded image URLs

Generates a cinematic video shot.

Parameters:

• prompt (string): Video description
• onProgress (function): Progress callback

Returns: Promise resolving to a video Blob

The following new services have been added to support the roadmap features:

Handles user authentication and session management.

Key Methods:

• signup(email, password, name) - Register new user
• login(email, password) - Authenticate user
• logout() - End session
• isAuthenticated() - Check authentication status

Manages projects and content organization.

Key Methods:

• createProject(name, description, ownerId) - Create new project
• addContentToCurrentProject(content) - Add content to active project
• exportProject(projectId) - Export project as JSON
• importProject(jsonString) - Import project from JSON

Enables batch processing of multiple generation requests.

Key Methods:

• batchGenerateCharacters(coreConcepts) - Generate multiple characters
• batchGeneratePlots(inputs) - Generate multiple plots
• batchGenerateConceptArt(prompts) - Generate multiple images
• cancelJob(jobId) - Cancel running batch job

Creates and manages shareable links for content.

Key Methods:

• createShareLink(type, prompt, concept) - Generate shareable link
• getSharedContent(shareId) - Retrieve shared content
• encodeContentForUrl(content) - Encode content for URL sharing
• copyToClipboard(shareLink) - Copy link to clipboard

Integrates with the official Marvel API.

Key Methods:

• searchCharacters(query) - Search Marvel characters
• getCharacter(characterId) - Get character by ID
• getPopularCharacters(count) - Get popular characters
• isConfigured() - Check API configuration

Manages custom character databases.

Key Methods:

• createDatabase(name, ownerId) - Create character database
• addCharacter(databaseId, characterData) - Add custom character
• searchCharacters(query) - Search custom characters
• exportDatabase(databaseId) - Export database as JSON

Exports content to various formats.

Key Methods:

• exportToPDF(content, filename) - Export to PDF
• exportToJSON(content, filename) - Export to JSON
• exportToXML(content, filename) - Export to XML
• exportToFBXMetadata(character, filename) - Export FBX metadata
• exportToMarkdown(content, filename) - Export to Markdown

Manages application configuration.

Key Methods:

• getVideoConfig() - Get video generation settings
• updateVideoConfig(updates) - Update video settings
• getBatchConfig() - Get batch processing settings
• resetToDefaults() - Reset all settings

Manages real-time collaboration using the BroadcastChannel API.

Key Methods:

• startSession(activeTab) - Open a collaboration session and announce presence
• endSession() - Notify peers and close the session
• broadcastTabChange(activeTab) - Notify peers of the active tab change
• broadcastContentUpdate(contentType, summary) - Broadcast a content update to collaborators

Reactive Signals:

• sessionActive - Whether a session is currently active
• peers - Live list of online collaborators
• peerCount - Number of online collaborators

Manages teams and role-based access control.

Key Methods:

• createTeam(name, description) - Create a new team owned by the current user
• updateTeam(teamId, name, description) - Update team name/description
• deleteTeam(teamId) - Delete a team (owner only)
• addMember(teamId, member) - Add a member to a team
• removeMember(teamId, userId) - Remove a member from a team
• updateMemberRole(teamId, userId, role) - Change a member's role
• addProject(teamId, projectId) - Associate a project with a team
• getRole(teamId) - Get the current user's role in a team
• canEdit(teamId) - Check if the current user can edit team content
• canManage(teamId) - Check if the current user can manage team settings

Reactive Signals:

• allTeams - All teams as a flat array
• myTeams - Teams the current user belongs to
• currentTeam - The currently selected team

Provides a cloud storage abstraction layer backed by localStorage.

Key Methods:

• save(localId, data) - Save a document to cloud storage
• load(localId) - Load a document from cloud storage
• delete(localId) - Delete a document and its sync record
• getRecord(localId) - Get the sync record for an item
• markLocalOnly(localId) - Mark an item as local-only without I/O

Reactive Signals:

• isSyncing - True while any save/delete operation is in progress
• allRecords - All tracked sync records
• pendingCount - Count of items not yet synced

npm run build

Output will be in the dist/ directory.

npm run dev

Runs on http://localhost:3000 with hot reload.

npm run preview

Currently, this project focuses on manual testing through the UI. Future versions will include:

• Unit tests for service methods
• Integration tests for AI workflows
• E2E tests for user flows

We welcome contributions! Please see our Contributing Guidelines for details.

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

• Follow the existing code style
• Add JSDoc comments for new functions
• Test your changes thoroughly
• Update documentation as needed

• Add user authentication - Full authentication system with JWT support, session management, and local storage persistence
• Implement project/session management - Create, save, load, and organize projects with multiple content items
• Add batch generation capabilities - Generate multiple items simultaneously with progress tracking
• Create shareable links for generated content - Share content via links with embedded data or local storage
• Integrate with Marvel API for character data - Search and retrieve official Marvel character data
• Add support for custom character databases - Create and manage custom character collections
• Add more art styles and themes - Expanded to 30 art styles and 20 narrative themes with visual style presets
• Support for longer video generation - Configurable timeouts up to 10 minutes (600 seconds)
• Export to industry-standard formats - Export to PDF, JSON, XML, FBX metadata, CSV, and Markdown
• Implement collaborative features - Real-time collaboration with BroadcastChannel-based user presence and cross-tab sync
• Add cloud storage integration - Abstract cloud storage layer with sync status tracking, ready for backend integration
• Team management and permissions - Create teams, manage members, and enforce role-based permissions (owner/editor/viewer)

• Add UI components for all new features (authentication, project management, batch generation, collaboration, teams)
• Extend real-time collaboration to multiple devices using WebSocket or Firebase
• Support for video chunking and longer sequences
• Advanced 3D export formats
• Backend integration to replace localStorage with a real cloud API

This project is licensed under the MIT License - see the LICENSE file for details.

• Google DeepMind for the incredible Gemini AI platform
• Marvel Comics for inspiring this tool
• Angular Team for the fantastic framework
• TailwindCSS for the utility-first CSS framework
• All contributors and users of this project

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Wiki: Project Wiki

This project is a fan-made tool and is not affiliated with, endorsed by, or sponsored by Marvel Comics, Disney, or Google. Marvel and all related characters are trademarks of Marvel Entertainment, LLC. This tool is intended for educational and creative purposes only.