Project Overview

Welcome to the 2511INS (InnStar CMS) documentation. This platform is a headless CMS built with high scalability and modularity in mind.

InnStar Limited — High-End Real Estate & Construction

This is the front-end repository for the InnStar Limited official website, built with Next.js and powered by a high-performance animation engine focusing on premium user experience and immersive visual storytelling.

🚀 Tech Stack

Core Framework

• Next.js 15+: Utilizing App Router, Server Components, and optimized static generation.
• Styled Components: Dynamic CSS-in-JS for theme-driven styling and high-performance design tokens.
• Tailwind CSS: Utility-first CSS for rapid layout development and responsive utilities.

Animation & Interaction

• GSAP (GreenSock): Orchestrating complex smooth-scrolling, parallax effects, and scroll-triggered animations.
• Framer Motion: Handling seamless page transitions and micro-interactions.
• Lenis: Providing high-fidelity smooth scrolling across all devices.

🛠️ Command Reference Matrix

This project supports both NPM and Yarn. Developers can use their preferred package manager:

⚙️ Environment Configuration

The application requires specific environment variables to function correctly across different stages. Copy .env.example to .env.local and populate the values.

Core & API

• NEXT_PUBLIC_BASE_URL: The secondary base URL for the application.
• NEXT_PUBLIC_SITE_URL: The primary front-end URL (e.g., https://innstarbd.com).
• NEXT_PUBLIC_API_URL: The back-end API endpoint for dynamic content and forms.
• ENCRYPTED_KEY: Used for secure API communication.

SEO & Metadata

• SITENAME: Used in the <title> tag template (e.g., THE SALTANAT).
• AUTHOR: The corporate name used in meta tags (e.g., InnStar Limited).
• NEXT_PUBLIC_META_KEYWORDS: Global keywords for search engine indexing.

Assets & Analytics

• NEXT_PUBLIC_CDN_URL: Base URL if assets are served via CDN.
• NEXT_PUBLIC_IMAGE_DOMAIN: Domain authorized for Next.js image optimization.
• NEXT_PUBLIC_GOOGLE_ANALYTICS: ID for tracking user behavior.

🎨 Design System & Styling

The project implements a proprietary DC Design System via src/styles/theme.js.

Spacing & Grid

• 4px Baseline: All spacing (margins, padding) follows a numeric scale based on a 4px module (Scale 1 = 4px, Scale 2 = 8px, etc.).
• Semantic Breakpoints:
  • xs: 329px (Small phones)
  • md: 767px (Large phones)
  • tab: 768px (Tablets)
  • laptop: 992px (Standard laptops)
  • uhd: 1920px (4K monitors)

Typography

The theme uses specialized font families:

• Primary: Mosvita (San-serif for UI and labels)
• Secondary: Cammron (Serif for headings and elegant body text)
• Accent: Careny (Used for overlines and call-to-actions)

📐 Module Development Guideline

The application is modular. Each section of a page is a "Module".

Step 1: Create the Component

Create a new file in src/modules/YourModuleName.jsx:

'use client';
import { Container, Row, Col } from 'react-bootstrap';

const YourModuleName = ({ data }) => {
  return (
    <section>
      <Container>
        <h2>{data.section_data.title}</h2>
      </Container>
    </section>
  );
};
export default YourModuleName;

Step 2: Register the Module

Add your module to src/render/ComponentRegistry.js to allow the CMS to render it dynamically:

import YourModuleName from '@/src/modules/YourModuleName';

export const COMPONENT_MAP = {
  // ... existing mappings
  your_module_type_from_api: YourModuleName,
};

🚢 Deployment Workflow (Manual)

Follow these steps to manually deploy the application to your production server via ZIP.

Step 1: Production Build

Generate the optimized production bundle on your local machine:

yarn build
# OR
npm run build

Step 2: Archive the Build

Create a ZIP archive of the necessary files. DO NOT include node_modules or .git as they are extremely large and should be handled on the server.

Files to include:

• .next/
• public/
• src/ (optional for production but recommended for debugging)
• package.json
• yarn.lock or package-lock.json
• next.config.mjs
• server.js (if using custom server)
• .env.production

Step 3: Upload & Extraction

1. Upload: Use SCP or SFTP to transfer the archive.zip to your server.
2. Extract: Access your server via SSH and unzip the archive:

   unzip archive.zip -d /var/www/innstar

Step 4: Server-Side Install

Navigate to your project directory on the server and install production dependencies:

yarn install --production
# OR
npm install --production

Step 5: Restart the Application

We use PM2 to manage the Node.js process. Restart the application to apply changes:

pm2 restart innstar-frontend
# OR (if by ID)
pm2 restart 0

🧼 Maintenance & Troubleshooting

Static Data Refreshing

If the UI doesn't reflect the latest CMS changes, trigger a build-time pre-fetch:

yarn build # This automatically triggers scripts/fetch-data.js

Common Issues

• Hydration Mismatch: Ensure CSS-in-JS (Styled Components) registry is correctly initialized in src/lib/registry.js.
• GSAP Context: Always wrap GSAP animations in useGsap or useEffect cleanup to avoid memory leaks during route changes.
• Port Conflict: Ensure the port specified in server.js or .env is not occupied by another process.

📄 License

Confidential & Private — Property of InnStar Limited. Developed by Dcastalia.

Backend Documentation (Yii2 Advanced CMS)

The backend is built on the Yii2 Advanced Framework, a high-performance PHP framework optimized for large-scale enterprise applications. It follows a clean separation of concerns between administration and data delivery.

🚀 Technology Stack

📁 Folder Structure Overview

🖼️ Media Library Picker Component

The CMS uses a centralized, reusable component for all media selections to ensure consistency across modules.

// Implementation sample in View files
echo $this->render('@backend/views/layouts/_media_selection', [
    'model' => $model,
    'attribute' => 'image_id',
    'identifier' => 'feature_image_slug'
]);

🔐 RBAC & Security

Granular access control is managed via the MDMSoft Yii2-Admin extension. Permissions are assigned to roles, which are then attached to backend users.

• Roles: Admin, Editor, Content Manager, Support.
• API Auth: JWT and Header-based authentication for secure frontend communication.

Core Backend Modules

The system is composed of several specialized modules handling specific CMS domains.

RESTful API Reference

The API serves as the bridge between the Yii2 data layer and the frontend, delivering optimized JSON payloads.

📡 GetReqDataController Endpoints

The primary controller for data delivery. Base URL: /api/get-req-data/

🔐 Global Security & Headers

• API Key: Requests should include the ENCRYPTED_KEY derived from the environment config.
• Response Format: Every API call returns a standardized JSON structure with status, message, and data.

Database Tech Stack

The system currently uses MySQL. The configuration is centralized to allow for easy scaling or technology swaps.

Configuration Path

Edit the following file to update connection strings:

How to change DB Technology

If you need to change the database (e.g., to PostgreSQL), follow these steps:

1. Update the dsn and class in common/config/main-local.php.
2. Ensure the appropriate PHP driver is installed.
3. Run migrations: php yii migrate.

User Manual & Directions

Follow this step-by-step guide to manage your website content efficiently using the InnStar CMS.

CMS Information

The InnStar CMS is designed for ease of use. After logging in, you will be greeted by the Dashboard.

Getting Started:

1. Access the Dashboard: Navigate to the /admin URL and log in with your credentials.

• Navigation Sidebar: Use the left sidebar to access different modules like Pages, Products, and Blogs.
• Global Search: Quickly find any resource using the search bar at the top (if enabled).

Media Library

The Media Library is the central hub for all your images, videos, and documents used across the CMS.

1. View Library

The main library view allows you to browse all uploaded assets in a responsive grid or list view.

• Asset Grid: Quickly identify images through thumbnails.
• Folders/Contexts: View assets organized by their usage context (Pages, Blogs, etc.).
• Search & Filter: Find specific files by name or type.

---

2. Upload Media

Easily add new assets to your library using the interactive upload tool.

1. Click the Upload button in the Media Library.
2. Drag and drop files or click to select from your computer.
3. The system will automatically optimize and process your files for web use.

---

3. Media Settings

Configure global rules for image optimization and processing.

• Image Sizes: Define default dimensions for different usage contexts.
• Compression: Control the balance between image quality and file size.

---

4. Media Garbage Cleanup

Maintain a lean system by identifying and removing unused or orphaned media files.

• Orphan Detection: Identify files that are not linked to any page or post.
• Bulk Removal: Clean up your server storage with a single click.

---

Media Picker (Global Component)

The Media Picker is a versatile popup used across all modules to select or upload images and files on the fly.

How to use:

• Select Existing: Click on any image in the grid to select it.
• Instant Upload: Switch to the upload tab within the picker to add new files without leaving your current page.
• Confirmation: Click Choose or Apply to link the media to your current resource.

Modules Reference

Detailed documentation for each administrative module in the CMS.

Page Module

The Page module is the heart of the CMS, allowing you to manage the website structure and content through a flexible, section-based system.

1. View All Pages

The Pages List provides a high-level overview of all website pages, their hierarchy, and their current status.

List Overview:

• Title: Displays the page title and its indentation (indicating hierarchy).
• Sections: Quick link to see how many content blocks are assigned to the page.
• Status: View whether a page is Active, Draft, or Archived.
• Actions: Quick access to view, update, or manage page settings.

---

2. Create New Page

Starting a new page requires defining its basic properties and URL structure.

1. Navigate to Pages > Add New.
2. Parent Page: Select if this is a sub-page (e.g., Services > Web Design).
3. Title & Slug: Enter the page name; the slug will auto-generate but can be customized.
4. Description: Add a short summary for the page header or SEO.
5. Click Create to save the initial record.

---

3. Update Page

After creation, you can refine a page's content, SEO, and visual assets through the update interface.

Key Update Areas:

• General Tab: Edit main titles, subtitles, and descriptions.
• Meta Data: Manage SEO titles and social sharing images.
• Buttons: Add dynamic call-to-action buttons directly to the page.
• Additional Fields: Add custom text data unique to this page.

---

4. Meta Data

Optimize your page for search engines and social media platforms.

• Meta Title: The title displayed in search engine results.
• Meta Description: A brief summary that appears under the title in search results.
• Meta Image: The image shown when the page link is shared on social media.

---

5. Page Gallery

Attach visual albums to your page content.

• Select from existing albums in the Gallery module.
• Choose how the gallery should be displayed (e.g., Grid or Slider).

---

6. Page Images

Manage secondary images and visual assets specifically for this page.

• Use the Media Picker to select or upload images.
• Assign images to specific layout placeholders.

---

7. Page Files

Manage downloadable documents and files attached to the page.

• Attach PDFs, Docs, or other files for user download.
• Set display labels for each file.

---

8. Page Data Template

For advanced layouts, you can define custom JSON data structures to drive specific frontend components.

• JSON Structure: Input custom data fields used by specialized templates.
• Dynamic Configuration: Control advanced behaviors without code changes.

---

9. Bulk Actions

Manage multiple pages simultaneously using the bulk action tool in the pages list.

How to use:

1. Select multiple pages using the checkboxes on the left.
2. Choose an action from the Bulk Action dropdown (e.g., Bulk Delete, Bulk Archive).
3. Click Apply to execute the action on all selected items.

---

Sections Management

Sections are the building blocks of your pages. Each page can have multiple sections, each with its own layout and content.

10. Create a Section

Add new layout blocks to your page by creating sections.

1. Click Add Section in the Page Update view.
2. Enter a Title and select the Template (this defines the layout).
3. Click Create to add the section.

To modify an existing section, click the Update icon in the sections list.

---

11. Section Tabs & Media

Sections have their own dedicated management tabs for handling specific content types.

Gallery

Attach image albums specific to this section.

Images

Manage section-specific visual assets.

Files

Attach downloadable documents to the section.

Posts

Manage the content blocks (Posts) nested within this section.

Data Template

Configure advanced JSON data for the section's template.

---

Posts Management

Posts are the individual content units within a section. They allow you to add repeating items like services, features, or team members.

12. View All Posts

See all posts assigned to a specific page or section.

---

13. Create a Post

Add new content blocks to your section.

1. Navigate to the Posts tab in a page or section.
2. Click Add Post.
3. Fill in the content fields and click Create.

---

14. Update a Post

Refine the content and visual appearance of individual posts.

Advanced Post Options:

• Post Images: Assign specific media to the post.
• Post Template: Override the section template for a specific post.

---

15. Archive Page

If a page is no longer needed but you want to keep the data, you can archive it.

1. In the Pages list, find the page you wish to archive.
2. Click the Status dropdown or select the item.
3. Confirm the Archive status change.
4. Archived pages can be viewed and restored from the Archived tab at the top of the pages module.

Product Module

Manage your product portfolio and project listings with advanced features for specifications, variations, and modular content.

1. View All Products

The product list provides a comprehensive overview of your catalog, including identifiers, categories, and status.

---

2. Create New Product

Add new products by defining their identity and initial SEO parameters.

1. Navigate to Products > Add New.
2. General Info: Enter Title, Category, and Type.
3. SEO: Populate meta titles and descriptions for better search visibility.
4. Click Create to save the product.

---

3. Update Product Details

Manage all aspects of an existing product through specialized management tabs.

Meta Data & SEO

Refine how the product appears in search results and social sharing.

Specifications

Add technical details, dimensions, or specific attributes.

Variations

Manage different versions (colors, sizes) of the product.

Gallery & Media

Upload and organize images specifically for this product.

Product Files

Attach manuals, brochures, or technical documents.

Data Templates

Configure custom layout templates for the product page.

---

4. Product Posts (Feature Blocks)

Create and manage modular content blocks to highlight specific product features.

Post Customization:

• Section Management: Organize posts into logical sections.
• Templates: Select from predefined layouts for your posts.
• Visual Assets: Manage images specifically for these feature blocks.

Import/Export Module

The Import/Export tool allows you to migrate data between environments and maintain offline backups of your CMS content.

Exporting Data:

1. Navigate to Import/Export in the main menu.
2. Select Model: Choose which module data you wish to export (e.g., Pages, Products, Blogs).
3. Configure Fields: Select specific fields or export the entire model structure.
4. Download: Click Export to generate and download a JSON/CSV file.

Blog Module

Publish and manage news articles, company updates, and blog posts with full SEO support.

1. View All Blog Posts

The blog list provides an overview of all articles, their categories, and publication status.

---

2. Create Blog Post

Start a new article by defining its core properties and initial content.

1. Click Add New in the Blog module.
2. Enter the Title, Category, and Short Description.
3. Populate the main Content area using the Rich Text Editor.
4. Click Create to save the post.

---

3. Update Blog Content & Images

Refine your article's layout and visual assets through the update interface.

Management Tabs:

• General: Edit the main article body and primary fields.
• Images: Manage the featured image and secondary visuals for the post.

---

4. Blog Meta Data

Optimize individual blog posts for search engines and social sharing.

Use the Meta Data tab to set unique SEO titles, keywords, and social sharing descriptions for every article.

---

5. Blog Templates

Choose different layout styles for your blog posts.

Select a pre-registered template from the dropdown to instantly change the visual appearance of your article on the frontend.

Forms & Submissions

Manage user inquiries, lead data, and automated communication generated from your website's interactive forms.

1. Form Management

Configure form fields, validation rules, and submission settings for each contact form on your site.

---

2. Submissions & Leads

View and export all data collected via website forms.

---

3. Subscriptions

Track and manage newsletter subscriptions and user opt-ins.

---

4. Email Logs & Notifications

Monitor all automated emails sent by the system to both administrators and users.

Gallery Module

Create and manage visual albums and image collections used throughout the website.

1. View All Galleries

The main gallery list displays all created albums and their current visibility status.

---

2. Create New Gallery

Start a new album by defining its title and basic properties.

1. Click Add New in the Gallery module.
2. Enter the Title and optional description.
3. Set the initial Status (Active/Draft).
4. Click Create to initialize the album.

---

3. Manage Gallery Items

After creating a gallery, you can add and organize multiple images within it.

Adding Images:

1. Open a gallery and navigate to the Posts or Items tab.
2. Click Add Post to add a new image block.
3. Use the Media Picker to select or upload an image.
4. Add an optional caption and sort order.

---

4. Archive Gallery

Hide galleries from the live site while retaining them for future use.

Use the status toggle in the list view to archive a gallery. Archived galleries can be filtered and restored at any time.

Categories

Centralized taxonomy management for Blogs and Products. Categories help in organizing your content into logical groups, making it easier for users to navigate your site.

1. View All Categories

The main categories list shows all existing taxonomies, their types, and current status.

• Global Organization: Manage categories used by Blog and Product modules.
• Hierarchy: Support for parent-child category structures.
• Status Tracking: See which categories are active or archived.

---

2. Create New Category

Add new content groupings to your system.

1. Navigate to Categories > Create New.
2. Title: Enter the display name for the category.
3. Type: Select whether this category is for Blogs, Products, or other content types.
4. Parent: Choose a parent category if this is a sub-category.
5. Click Save to finalize.

---

3. Archive Category

Deactivate categories that are no longer needed without deleting the underlying data.

• Soft Delete: Archiving hides the category from frontend filters but keeps it in the database for reference.
• Restoration: Archived categories can be reactivated at any time.

Jobs & HR

Manage website recruitment, post career opportunities, and track applications received through the careers portal.

1. View All Jobs

The main job list provides an overview of all active, draft, and archived job openings.

---

2. Post New Job

Create a new career opportunity by defining the job title, category, and requirements.

---

3. Update Job Details

Modify existing job descriptions, update deadlines, or change the status of a posting.

Menu Builder

The Menu Builder allows you to create and manage dynamic navigation structures for your website, supporting nested links and drag-and-drop reordering.

1. View All Menus

The main menu list displays all registered navigation structures (e.g., Main Header, Footer Menu).

---

2. Create New Menu

Define a new navigation container by providing a name and a unique identifier.

---

3. Update Menu

Manage the top-level properties and organize the items within a menu.

---

4. Manage Menu Items

Add, edit, or remove individual links within a menu. You can link to internal pages, external URLs, or content modules.

Key Features:

• Drag-and-Drop: Easily reorder items or create sub-menus by dragging items into a nested position.
• Link Types: Choose between internal pages, blog posts, products, or custom external links.
• Attributes: Add custom CSS classes or target attributes (e.g., open in new tab).

Addresses

Manage corporate office locations, branches, and contact information for map integration and site-wide display.

1. View Addresses

The main list displays all registered locations and their primary contact details.

---

2. Create New Address

Add a new location by providing coordinates, physical address, and contact metadata.

---

3. Update Address

Modify existing location data or update map coordinates for frontend accuracy.

User Access & RBAC

Manage administrative users, track system activity, and configure granular access control via Roles and Permissions.

1. User Management

Create and manage backend administrators and editors.

---

2. Activity Logs

Monitor system-wide actions taken by administrative users for security and auditing.

---

3. RBAC (Roles & Permissions)

Define custom roles and assign specific permissions to control access to CMS modules.

RBAC Workflow:

• Create Roles: Define functional roles like "Editor" or "Support".
• Assign Permissions: Attach specific route access to each role.
• Link to Users: Assign one or more roles to an administrative user.

Templates

Manage visual layout templates for different content types, allowing editors to choose from pre-defined designs.

1. View Templates

The main list displays all registered templates and their usage across the site.

---

2. Create New Template

Register a new layout by providing a name, identifier, and a preview screenshot to help editors.

Content Types

Define and organize different types of content (Pages, Sections, Posts) to categorize them effectively.

1. View Content Types

Browse the list of all active and archived content identifiers.

---

2. Manage Content Types

Create or update types to match your website's data structure requirements.

---

3. Archive & Status

Archive unused types to keep the administrative interface clean without losing historical data integrity.

Administration

System maintenance, data integrity tools, and advanced administrative utilities.

1. Garbage Cleanup

Identify and remove orphaned files that are no longer linked to any content, keeping your storage optimized.

---

2. JSON Support & Debugging

Advanced views for inspecting raw JSON data payloads delivered by the API.

---

3. Bulk Tools & System Operations

Perform system-wide operations like re-generating assets or downloading data backups.

Global Configuration

Site-wide settings, module behavior, and system optimizations are managed here.

1. Global Settings

Configure core website properties, social media links, and contact metadata via a step-by-step interface.

---

2. Product Attributes

Define custom specifications and attributes for your product catalog.

---

3. Media Settings

Manage image optimization rules, folder structures, and custom media fields.

---

4. API Documentation & Advanced Fields

Access the built-in Swagger documentation and manage system-wide extra fields for content modules.

Technical Support

For technical assistance and inquiries, please contact Dcastalia Limited.