Frontend Architecture

Relevant source files

The following files were used as context for generating this wiki page:

• app/_layout.tsx
• contexts/AuthContext.tsx
• contexts/ChatContext.tsx
• utils/logger.ts
• README.md
• REPORTE_CHAT_MODULE.md
• FIXES-APLICADOS.md

The ElmecV2 frontend is a multi-platform mobile application built with React Native and Expo. It provides a comprehensive system for managing service requests, including real-time chat, user management, and an administrative dashboard. The architecture is designed to be modular, scalable, and maintainable, leveraging modern technologies for state management, navigation, and backend communication.

The architecture emphasizes a clear separation of concerns, with dedicated contexts for features like authentication and chat, a centralized service layer for backend interactions (primarily with Supabase), and reusable UI components. This structure supports robust features such as real-time updates, offline functionality, and detailed performance logging.

Core Technologies

The frontend stack is built upon a set of modern and widely-adopted libraries and frameworks.

Technology	Role	Description
React Native 0.74	Core Framework	Provides the foundation for building native apps for iOS and Android from a single JavaScript codebase.
Expo 51	Development Platform	A platform and set of tools built around React Native to simplify development, building, and deployment.
TypeScript	Language	Adds static typing to JavaScript for improved code quality and maintainability.
Expo Router	Navigation	Implements file-system-based routing for navigating between screens.
Zustand	Global State	A lightweight state management solution for handling global application state.
TanStack Query	Server State	Manages asynchronous operations, caching, and synchronization of server state.
Supabase	Backend Service	Used for authentication, database (PostgreSQL), real-time subscriptions, and storage.

Sources: README.md

Project Structure

The project follows a standard feature-oriented directory structure that promotes modularity and separation of concerns.

elmecV2-Demo/
├── app/                  # Expo Router screens and layouts
├── components/           # Reusable UI and form components
├── contexts/             # React Context providers (Auth, Chat)
├── hooks/                # Reusable custom hooks
├── services/             # API services (e.g., SupabaseService)
├── store/                # Global state management (Zustand)
├── utils/                # Utility functions (logger, errorHandler)
├── types/                # TypeScript type definitions
└── assets/               # Static assets (images, fonts)

Sources: README.md

This diagram illustrates the high-level component hierarchy.

State Management

The application employs a hybrid strategy for state management, using both a global store and scoped contexts.

Global State (Zustand)

Zustand is designated for managing global application state, such as user settings or application-wide notifications. The store is intended to be defined in the store/ directory.

Sources: README.md

Scoped State (React Context)

For domain-specific state that is shared across a subset of components, the application uses React's Context API. This is prominently used for Authentication and Chat.

AuthContext

AuthContext manages the user's authentication state, session information, and user profile. It exposes the isAuthenticated flag, the user object, and functions for signIn, signOut, and signUp. The provider wraps the entire application to make authentication state globally accessible.

Sources: contexts/AuthContext.tsx

ChatContext

ChatContext encapsulates all logic related to real-time messaging. It manages chat rooms, messages, real-time subscriptions to Supabase, and presence tracking (e.g., "typing..." indicators). This isolates the complex chat logic from the UI components.

Sources: contexts/ChatContext.tsx, REPORTE_CHAT_MODULE.md

Routing and Navigation

Routing is handled by Expo Router, which uses a file-system-based convention. The app/ directory defines the routes.

The root layout, app/_layout.tsx, is the main entry point. It orchestrates the initial view by wrapping the application in necessary providers (AuthProvider, ChatProvider) and determining which screen to show based on the authentication state.

Initial App Load Flow

This diagram shows the logic executed when the app first loads.

The RootLayout component checks the isAuthenticated flag from AuthContext and uses the Redirect component from Expo Router to navigate the user accordingly.

Authentication Flow

Authentication is managed by AuthContext and powered by Supabase Auth. The flow ensures that users are securely logged in and their session is maintained.

This sequence diagram illustrates the sign-in process.

Real-time Functionality (Chat)

The chat module is a key feature that relies on Supabase's real-time capabilities. The ChatContext is responsible for managing WebSocket connections and subscriptions.

Real-time Message Subscription

When a user enters a chat room, the ChatContext establishes a subscription to the messages table in the database, filtered by the current roomId.

// Source: contexts/ChatContext.tsx:192-210
const channel = supabase
  .channel(`chat_room_${roomId}`)
  .on('postgres_changes', {
    event: 'INSERT',
    schema: 'public',
    table: 'messages',
    filter: `chat_room_id=eq.${roomId}`
  }, async payload => {
    // Logic to handle new incoming message
    // Update local messages state (optimistic update may be used)
    // Send a notification
  })
  .subscribe();

Sources: contexts/ChatContext.tsx:192-210, REPORTE_CHAT_MODULE.md, FIXES-APLICADOS.md

This sequence diagram shows how a message is sent and received in real-time between two users.

Utilities

Logging

The application includes a robust Logger class for structured logging, which is crucial for debugging and monitoring in both development and production environments.

Logger Class Structure

This diagram outlines the Logger class and its main components.

Configuration and Usage

The logger is configured based on the environment (EXPO_PUBLIC_ENVIRONMENT). In development, it logs DEBUG level messages and above to the console. In production, it only logs WARN and above and can be configured to send ERROR and FATAL logs to a remote endpoint.

Key Features:

• Log Levels: Supports DEBUG, INFO, WARN, ERROR, and FATAL.
• Contextual Logging: Allows adding a context string and a data object to logs.
• Environment-Aware: Automatically adjusts logging behavior for development vs. production.
• Remote Logging: Can send critical logs to a specified remote server.
• Performance Timers: Includes a startTimer method to measure execution time of functions.
• Specialized Loggers: Provides dedicated methods for logging user actions and API calls.

Sources: utils/logger.ts

Summary

The frontend architecture of ElmecV2 is robust, modern, and well-structured. It effectively leverages the Expo ecosystem and React Native for cross-platform development. Key architectural decisions include:

• File-based routing with Expo Router for clear navigation structure.
• A hybrid state management approach combining Zustand for global state and React Context for scoped, feature-specific state.
• Direct and effective integration with Supabase for backend services, especially its real-time capabilities for the chat module.
• A comprehensive, centralized logging utility that supports different environments and provides tools for performance monitoring and debugging.

This architecture provides a solid foundation for building, maintaining, and scaling the application's features.