Adara Digital Signage Platform Development Assistant

Expert assistant for the Adara Digital Signage Platform - an enterprise multi-tenant digital signage system with advanced RBAC, AI-powered content moderation, and cross-platform support.

Project Overview

**Architecture**: FastAPI Backend + Next.js Frontend + Flutter Mobile App

**Target Market**: UAE/Dubai enterprise digital signage and multi-company management

**Status**: 85% complete with advanced RBAC, AI moderation, and device management

Core Business Model

Technology Stack

```

Frontend: Next.js 15 + React 19 + TypeScript + Tailwind CSS + shadcn/ui

Backend: FastAPI (Python 3.12+) + MongoDB + Azure Services

Mobile: Flutter 3.24+ with advanced device authentication

Package Manager: UV (fast Python package installer) - REQUIRED

AI Integration: Multi-provider (Gemini, OpenAI, Claude, Ollama) with failover

Infrastructure: Azure UAE Central + Docker + Kubernetes

Security: JWT + API Keys + Advanced RBAC + Multi-tenant isolation

```

Instructions

1. Understand the Project Context

When starting any task:

2. Development Environment Setup

**CRITICAL**: Always use UV package manager for Python development:

```bash

Install UV (if not present)

curl -LsSf https://astral.sh/uv/install.sh | sh # macOS/Linux

or PowerShell for Windows: irm https://astral.sh/uv/install.ps1 | iex

Setup backend

cd backend/content_service

uv venv

uv sync

uv run uvicorn app.main:app --reload --port 8000

Setup frontend

cd frontend

npm install

npm run dev # Runs on port 3000

```

3. Code Architecture Principles

Follow the established clean architecture:

4. RBAC Implementation

When working with permissions:

```python

Always check permissions with context

def hasPermission(user, resource, action, context=None):

if user.user_type == "SUPER_USER":

return True

permission = f"{resource}_{action}"

if permission not in user.permissions:

return False

# Apply company isolation

if context and context.get("company_id") != user.company_id:

return False

return True

```

Permission format: `{resource}_{action}` (e.g., `content_create`, `device_manage`, `analytics_read`)

5. Multi-Tenant Data Isolation

Always enforce company-level isolation:

6. AI Content Moderation

When working with content:

7. Device Authentication

Devices authenticate with:

Validate all three headers for device endpoints.

8. Testing Approach

```bash

Backend tests

cd backend/content_service

uv run pytest tests/ -v

Frontend tests

cd frontend

npm test

Specific test file

uv run pytest tests/test_auth.py -v

```

9. Database Operations

10. Common Development Tasks

**Adding a new permission:**

1. Add to permission enum in `app/models/user.py`

2. Update role-permission mappings in RBAC service

3. Add permission check in relevant endpoint

4. Update frontend permission guards

**Creating new API endpoint:**

1. Define route in appropriate router (`app/routers/`)

2. Add permission decorator: `@require_permission("resource_action")`

3. Implement company_id filtering if needed

4. Add corresponding TypeScript types in frontend

5. Write integration test

**Adding AI provider:**

1. Create agent class inheriting from `BaseAIAgent`

2. Implement `analyze_content()` method

3. Add to agent registry in `app/services/content_moderation.py`

4. Add API key to environment variables

5. Update failover chain configuration

11. Production Deployment Considerations

12. Code Quality Standards

13. Known Issues and Constraints

14. Getting Help

When uncertain:

1. Check `backend/content_service/app/` for backend code structure

2. Review `frontend/src/` for Next.js component patterns

3. Consult `app/models/` for data schemas

4. Check existing tests in `tests/` for usage examples

5. Review environment variables in `.env.template`

Key Files Reference

| File | Purpose |

|------|---------|

| `backend/content_service/app/main.py` | FastAPI application entry point |

| `backend/content_service/app/routers/auth.py` | Authentication endpoints |

| `backend/content_service/app/services/rbac.py` | RBAC permission engine |

| `backend/content_service/app/services/content_moderation.py` | AI moderation service |

| `backend/content_service/app/models/` | MongoDB data models |

| `frontend/src/app/dashboard/` | Main dashboard pages |

| `frontend/src/components/` | Reusable React components |

| `frontend/src/lib/api/` | API client functions |

| `seed_data.py` | Database seeding script |

Examples

Example 1: Adding a new company role

```python

1. Update enum in app/models/user.py

class CompanyRole(str, Enum):

ADMIN = "ADMIN"

REVIEWER = "REVIEWER"

EDITOR = "EDITOR"

VIEWER = "VIEWER"

ANALYST = "ANALYST" # New role

2. Define permissions in app/services/rbac.py

ROLE_PERMISSIONS = {

CompanyRole.ANALYST: [

"analytics_read",

"analytics_advanced",

"content_read"

]

}

3. Update frontend types in src/types/user.ts

export type CompanyRole = 'ADMIN' | 'REVIEWER' | 'EDITOR' | 'VIEWER' | 'ANALYST';

```

Example 2: Implementing a protected endpoint

```python

from app.services.rbac import require_permission

from app.models.user import User

@router.get("/content/{content_id}")

@require_permission("content_read")

async def get_content(

content_id: str,

current_user: User = Depends(get_current_user)

):

# Company isolation

content = await Content.find_one({

"_id": content_id,

"company_id": current_user.company_id

})

if not content:

raise HTTPException(status_code=404, detail="Content not found")

return content

```

Example 3: Device authentication

```typescript

// Frontend device API call

const headers = {

'X-Device-ID': device.id,

'X-API-Key': device.apiKey,

'X-Company-ID': device.companyId,

'Content-Type': 'application/json'

};

const response = await fetch(`${API_BASE}/devices/content`, { headers });

```

Important Notes