feat: Add coding guidelines, testing guidelines, and architecture doc…

…umentation

README.md

@@ -1,33 +1,135 @@
-# telware_cross_platform
+# Telware Cross-Platform Team Repository
 
 <!-- STATIC ANALYSIS BADGES -->
 
-[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=TelwareSW_telware_cross_platform&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=TelwareSW_telware_cross_platform)
 [![Lines of Code](https://sonarcloud.io/api/project_badges/measure?project=TelwareSW_telware_cross_platform&metric=ncloc)](https://sonarcloud.io/summary/new_code?id=TelwareSW_telware_cross_platform)
 [![Technical Debt](https://sonarcloud.io/api/project_badges/measure?project=TelwareSW_telware_cross_platform&metric=sqale_index)](https://sonarcloud.io/summary/new_code?id=TelwareSW_telware_cross_platform)
 [![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=TelwareSW_telware_cross_platform&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=TelwareSW_telware_cross_platform)
 [![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=TelwareSW_telware_cross_platform&metric=security_rating)](https://sonarcloud.io/summary/new_code?id=TelwareSW_telware_cross_platform)
 [![Vulnerabilities](https://sonarcloud.io/api/project_badges/measure?project=TelwareSW_telware_cross_platform&metric=vulnerabilities)](https://sonarcloud.io/summary/new_code?id=TelwareSW_telware_cross_platform)
 
-A new Flutter project.
+Welcome to the **Telware Cross-Platform Team's** repository! This project is part of the Telware initiative to recreate the Telegram app. Our team is responsible for building the **Flutter-based cross-platform implementation**, ensuring seamless functionality across Android, iOS, and other supported devices.
+
+## Table of Contents
+
+1. [Project Overview](#project-overview)
+2. [Setup Instructions](#setup-instructions)
+3. [Project Structure](#project-structure)
+4. [Development Guidelines](#development-guidelines)
+5. [Testing](#testing)
+6. [Contributing](#contributing)
+7. [License](#license)
+8. [Additional Documentation](#additional-documentation)
+
+---
+
+## Project Overview
+
+This repository contains the cross-platform codebase developed using Flutter. Our responsibilities include:
+
+- Building the core UI and app logic.
+- Ensuring feature parity across platforms (Android, iOS).
+- Collaborating with Backend, Frontend, DevOps, and Testing teams.
+- Delivering a high-quality, performant, and reliable application.
+
+For a detailed understanding of the project workflow, refer to [docs/PROJECT_FLOW.md](docs/PROJECT_FLOW.md).
+
+## Setup Instructions
+
+### Prerequisites
+
+- **Flutter SDK**: Version `3.24.3` ([Installation Guide](https://docs.flutter.dev/get-started/install))
+- **Dart SDK**: Bundled with Flutter
+- **Development Environment**:
+  - Android Studio (for Android builds)
+- **Access to Backend Services**: Contact the backend team for API credentials and documentation.
+
+### Steps to Run the Project
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/TelwareSW/telware_cross_platform.git
+   cd telware_cross_platform
+   ```
+
+2. Install dependencies:
+   ```bash
+   flutter pub get
+   ```
+
+3. Run the app on a connected device or emulator:
+   ```bash
+   flutter run
+   ```
+
+4. To build platform-specific packages:
+   - **Android**: `flutter build apk`
+   - **iOS**: `flutter build ios`
+
+---
+
+## Project Structure
+
+```plaintext
+.
+├── lib/                # Core application code
+│   ├── components/     # Reusable UI components
+│   ├── screens/        # Screens and page-level widgets
+│   ├── services/       # Backend API integrations and business logic
+│   ├── utils/          # Utility functions and helpers
+│   └── main.dart       # Application entry point
+├── test/               # Unit and widget tests
+├── docs/               # Documentation files
+├── pubspec.yaml        # Flutter dependencies configuration
+└── README.md           # Project overview and setup
+```
 
 ---
 
-## :bar_chart: Project Flow
+## Development Guidelines
 
-For a detailed overview of our project's branching strategy, commit conventions, and overall workflow, please refer to the [PROJECT_FLOW.md](./docs/PROJECT_FLOW.md) document.
+- **Coding Standards**: Follow the guidelines defined in [docs/CODING_GUIDELINES.md](docs/CODING_GUIDELINES.md).
+- **Branching Strategy**: Use feature branches and maintain a linear Git history. Refer to [docs/PROJECT_FLOW.md](docs/PROJECT_FLOW.md).
+- **Commit Messages**: Use the [Conventional Commits](https://www.conventionalcommits.org/) format.
 
 ---
 
-## Getting Started
+## Testing
+
+1. Run unit tests:
+   ```bash
+   flutter test
+   ```
+
+2. Run integration tests:
+   ```bash
+   flutter drive --target=test_driver/app.dart
+   ```
+
+For more details, refer to [docs/TESTING.md](docs/TESTING.md).
 
-This project is a starting point for a Flutter application.
+---
+
+## Contributing
+
+We welcome contributions from all team members! To contribute:
+
+1. Fork the repository.
+2. Create a feature branch: `git checkout -b feature/your-feature`.
+3. Commit your changes: `git commit -m "feat: your feature description"`.
+4. Push to your branch: `git push origin feature/your-feature`.
+5. Submit a pull request.
+
+Refer to [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) for more information.
+
+---
 
-A few resources to get you started if this is your first Flutter project:
+## Additional Documentation
 
-- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab)
-- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook)
+- [Architecture Overview](docs/ARCHITECTURE.md)
+- [Contributing Guidelines](docs/CONTRIBUTING.md)
+- [Testing Guide](docs/TESTING.md)
+- [Coding Standards](docs/CODING_GUIDELINES.md)
+- [Project Flow](docs/PROJECT_FLOW.md)
 
-For help getting started with Flutter development, view the
-[online documentation](https://docs.flutter.dev/), which offers tutorials,
-samples, guidance on mobile development, and a full API reference.
+For questions or further assistance, feel free to reach out via the project Slack channel or raise an issue in this repository.

docs/ARCHITECTURE.md

@@ -0,0 +1,130 @@
+# Telware Cross-Platform Architecture
+
+This document provides a detailed overview of the architecture of the Telware Cross-Platform application. It complements the other documentation files in the `docs/` folder, including:
+
+- [README.md](../README.md): Project overview and getting started guide.
+- [CODING_GUIDELINES.md](./CODING_GUIDELINES.md): Coding standards and conventions.
+- [CONTRIBUTING.md](./CONTRIBUTING.md): Guidelines for contributing to the project.
+- [PROJECT_FLOW.md](./PROJECT_FLOW.md): Development workflow and branching strategy.
+- [TESTING.md](./TESTING.md): Testing strategy and best practices.
+
+## Overview
+
+The Telware Cross-Platform application is developed using [Flutter](https://flutter.dev/), enabling seamless deployment across multiple platforms, including:
+
+- **Mobile:** Android, iOS
+- **Web:** Browser-based deployment
+- **Desktop:** Linux, macOS, and Windows
+
+The use of a unified codebase ensures consistency in functionality, design, and performance across these platforms.
+
+## Project Structure
+
+The repository is organized to separate platform-specific and shared code, promoting modularity and ease of maintenance.
+
+### **Platform-Specific Directories**
+
+- **`android/`**: Android-specific configurations and native code.
+- **`ios/`**: iOS-specific configurations and native code.
+- **`web/`**: Web-specific configurations such as `index.html`.
+- **`linux/`**, **`macos/`**, **`windows/`**: Configurations and native integrations for desktop platforms.
+
+### **Shared Directory**
+
+- **`lib/`**: Core Dart codebase shared across platforms:
+  - **UI Components:** Widgets for a consistent user interface.
+  - **Business Logic:** State management and application logic.
+  - **Services:** API integrations, database interactions, etc.
+  - **Utils:** Helper functions and utilities.
+
+## Key Architectural Features
+
+### **Flutter Framework**
+
+Flutter provides a declarative UI framework that enables:
+
+- **Hot Reload:** Rapid feedback during development.
+- **Customizability:** Native performance with platform-specific customization.
+- **Cross-Platform Consistency:** Shared design system and behavior.
+
+### **State Management**
+
+State management solutions like Provider, Riverpod, or Bloc are used to:
+
+- Ensure scalability for complex features.
+- Improve code reusability and modularity.
+- Maintain application state efficiently.
+
+### **Platform Channels**
+
+Flutter's platform channels enable interaction between Dart and native code for features like:
+
+- Accessing device hardware (e.g., camera, GPS).
+- Using platform-specific APIs (e.g., Android's Intents, iOS's Core Data).
+
+### **Modular Design**
+
+- Separation of concerns is achieved through modules for UI, services, and utilities.
+- Modules facilitate easier testing, debugging, and development.
+
+## Development Workflow
+
+Refer to [PROJECT_FLOW.md](./PROJECT_FLOW.md) for a detailed explanation of the development workflow. Key highlights:
+
+- **Branching Strategy:**
+  - `main`: Production-ready code.
+  - `develop`: Latest stable development code.
+  - `feature/` and `bugfix/` branches for individual changes.
+- **CI/CD Pipelines:** Automate testing and deployment to ensure quality.
+
+## Quality Assurance
+
+### **Testing**
+
+The project follows rigorous testing practices as described in [TESTING.md](./TESTING.md):
+
+- **Unit Tests:** Validate individual components and logic.
+- **Widget Tests:** Ensure UI behaves as expected.
+- **Integration Tests:** These are provided by our dedicated testing team, who maintain a separate repository to ensure comprehensive validation of the application in real-world scenarios.
+
+### **Code Quality**
+
+- Adheres to the [coding guidelines](./CODING_GUIDELINES.md).
+- Code reviews are mandatory for all pull requests.
+
+### **Security**
+
+- Sensitive data is managed using secure storage solutions.
+- Regular dependency audits ensure the integrity of third-party libraries.
+
+## Setting Up the Project
+
+Follow these steps to set up the project locally:
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/TelwareSW/telware_cross_platform.git
+   ```
+
+2. Navigate to the project directory:
+   ```bash
+   cd telware_cross_platform
+   ```
+
+3. Fetch dependencies:
+   ```bash
+   flutter pub get
+   ```
+
+4. Run the application on your desired platform:
+   ```bash
+   flutter run
+   ```
+
+## Future Improvements
+
+- Advanced state management for enhanced scalability.
+- Deeper integration of platform-specific features.
+- Increased test coverage for critical modules.
+
+For more details, explore the other documentation files in the `docs/` folder or visit the [repository](https://github.com/TelwareSW/telware_cross_platform).

docs/CODING_GUIDELINES.md

@@ -0,0 +1,48 @@
+# Coding Guidelines
+
+To ensure consistency and maintainability across the project, please follow these coding standards:
+
+## General Guidelines
+
+- Write clean and readable code.
+- Follow the [Effective Dart](https://dart.dev/guides/language/effective-dart) guidelines.
+- Avoid hardcoding values; use constants or configuration files.
+- Ensure all code changes are tested before committing.
+
+## File and Folder Organization
+
+- Group related files together (e.g., components, screens, services).
+- Keep files small and focused; a single file should ideally handle one responsibility.
+- Use descriptive and consistent file and folder names in `snake_case`.
+
+## Naming Conventions
+
+- **Classes**: Use `PascalCase` (e.g., `UserModel`, `MainScreen`).
+- **Variables**: Use `camelCase` (e.g., `userName`, `isLoggedIn`).
+- **Constants**: Use `UPPER_SNAKE_CASE` (e.g., `MAX_RETRY_COUNT`).
+
+## Code Comments
+
+- Write meaningful comments explaining the “why” behind the logic, not the “what.”
+- Document all public methods and classes using DartDoc.
+  ```dart
+  /// Calculates the total price of items in the cart.
+  double calculateTotalPrice(List<Item> items) {
+    ...
+  }
+  ```
+
+## Flutter-Specific Guidelines
+- Use widgets efficiently; prefer `const` constructors where possible.
+- Separate business logic from UI using patterns like Provider, or Riverpod.
+- Avoid nesting widgets deeply; extract them into reusable components.
+
+## Git Commit Guidelines
+- Use descriptive commit messages (e.g., `feat: add login functionality`).
+- Follow the [Conventional Commits](https://www.conventionalcommits.org/) specification.
+
+## Code Reviews
+- All pull requests must be reviewed and approved before merging.
+- Address all comments from reviewers before marking a PR as ready.
+
+By adhering to these guidelines, we ensure a high standard of quality and a codebase that's easier to maintain and scale.