This repository organises the development of HEXGO, a multiplayer geolocation-based territory capture game. HEXGO allows players to conquer hexagons on a real map, compete in global and team leaderboards, participate in races, and interact socially through an activity feed and notifications. Below are the main components of the project and installation instructions for the two repositories in the HEXGO-Studio organisation (which are private and not publicly accessible): the backend and the frontend.

1. General Description
2. Repository Structure
3. Backend – HEXGO_backend
   • Features
   • Prerequisites
   • Setup and Running
4. Frontend – HEXGO_frontend
   • Features
   • Prerequisites
   • Setup and Running
5. Architecture and Workflows
6. Contributing and License

HEXGO is a real-world capture-the-flag style game. The game map is divided into hexagons from the H3 library; each player or team can capture these hexagons by physically travelling to their location. The system rewards activity with points, badges, and positions in a global, friends, and team ranking. In addition to the territory mechanics, HEXGO includes:

• Real-time races – competitions where the distance travelled is recorded while the user keeps the app in the foreground or background.
• Social feed – an activity wall displaying captures, achievements, and races from friends, the team, and the global community, with comments and notifications.
• Notification system – push alerts via Firebase Messaging and local notifications for important events (e.g. loss of a territory, end of a capture streak, friend invitations, etc.). The backend runs background tasks to detect inactivity and generate alerts.
• Gamification through badges and seasons – achievement collection, timed seasons with specific rules and rewards.
• Team management – creation and administration of teams, invitations, roles, and collective competition.

The project is split into two independent repositories: a backend built with FastAPI and a cross-platform frontend developed with Flutter.

The HEXGO-Studio GitHub profile contains two private repositories. These repositories are not publicly accessible; you must have permissions granted by the team to access them.

The following sections detail both parts separately.

The backend is built with FastAPI and organises its code into thematic modules under src/routers. Each module exposes JWT-authenticated REST endpoints for different aspects of the game:

The database.py file defines the connection to PostgreSQL, first attempting to read the INTERNAL_DATABASE_URL environment variable (for Render deployments) and otherwise falling back to local variables (DB_HOST_LOCAL, DB_NAME_LOCAL, DB_USER_LOCAL, DB_PASS_LOCAL). No ORM is used: queries are executed directly with psycopg2.

The API root (src/main.py) instantiates the FastAPI application with metadata (title="HEXGO API", description and version) and mounts all routers. The base endpoint returns a simple message indicating the server is running.

• Python 3.10 or higher.
• PostgreSQL locally or as a managed service.
• (Optional) Render.com for automatic deployment; in this case, the INTERNAL_DATABASE_URL environment variable and credentials for external services (e.g. Firebase Cloud Messaging tokens for push notifications) must be configured.

1. Clone the repository (private repository):

   This project is not distributed publicly. To clone it you must have access granted by the HEXGO team and use your credentials (personal token or SSH key). An example using HTTPS with a token:

   git clone https://<user>:<token>@github.com/HEXGO-Studio/HEXGO_backend.git
   cd HEXGO_backend

2. Create a virtual environment (recommended) and install dependencies:

   python3 -m venv venv
   source venv/bin/activate
   pip install --upgrade pip
   pip install -r requirements.txt

3. Configure environment variables. Create a .env file in the root and define the database credentials. Example:

   # Local database
   DB_HOST_LOCAL=localhost
   DB_NAME_LOCAL=hexgo_db
   DB_USER_LOCAL=hexgo_user
   DB_PASS_LOCAL=secure_password

   # Managed database (Render)
   INTERNAL_DATABASE_URL=postgresql://user:password@host:port/database

   # Email variables for verification (optional)
   MAIL_USERNAME=your_email@gmail.com
   MAIL_PASSWORD=email_password
   MAIL_FROM=HEXGO
   MAIL_PORT=587
   MAIL_SERVER=smtp.gmail.com

4. Initialise the database. Create the required tables by running SQL scripts (not included) or using your own migration file. SQL queries are currently embedded in the controllers; review src/routers/*.py for the required schema.

5. Run the development server. Start the application with Uvicorn:

   uvicorn src.main:app --reload --host 0.0.0.0 --port 8000

The root endpoint (http://localhost:8000/) will display a simple message and the Swagger documentation will be available at /docs.

6. (Optional) Deploy to Render. Configure a FastAPI instance and set the INTERNAL_DATABASE_URL variable in the environment variables section. Render will automatically install dependencies from requirements.txt and run src/main.py.

The frontend is a Flutter application that consumes the backend API and offers a rich, gamified experience. Key features include:

• Main screen with tab navigation – a bottom bar provides quick access to the feed, map, races, ranking, notifications, and profile. When the main screen loads, it fetches the profile photo and unread notification count via HTTP requests to the backend.

• Map with H3 hexagons – flutter_map and mapbox are used to render the map. A timer updates zones and user statistics every few seconds by calling the /zonas/mapa and /ranking/mi-estado endpoints. Users can apply filters (all zones, team zones, my territories, friends, advanced filters) and tap individual hexagons to view details. Centroids and labels are calculated using geometric algorithms.

• Ranking – displays player, team, friends, and historical leaderboards. Users can filter by scope (global or city), period (this week, month, season), and search by name. When certain leaderboards are locked, users are informed via an explanatory dialogue.

• My territories – lists the hexagons belonging to the player, showing their integrity and last capture date. Territories at risk of being lost are highlighted, and users can jump to the map from a specific territory.

• Social feed – a periodically updated wall displaying captures, achievements, and races from global users, friends, or the team. Users can filter by activity type and view their current statistics (points and ranking position).

• Races – real-time race tracking. A background service (background_service.dart) records the user's position, calculates distances with geolocator, and sends updates to the race screen and the database.

• Notifications – integration with Firebase Messaging for push notifications and flutter_local_notifications for local alerts. Notifications are managed in notification_service.dart and displayed on the notifications screen.

• Team management, achievements, and settings – additional screens allow creating and managing teams, viewing achievements and badges, editing the profile, changing the language (Spanish/English), units (km/miles), privacy, and notification preferences. These settings are stored in SharedPreferences and synchronised with the backend via SettingsService.

• Flutter 3.10 or higher. Install the SDK following the official guide.
• Android Studio or Xcode to build native applications or emulate devices, along with the Android/iOS SDKs.
• A Firebase account to configure push messages. The app uses firebase_core and firebase_messaging; register the application in Firebase and download the configuration files (google-services.json for Android and GoogleService-Info.plist for iOS).
• (Optional) A Mapbox key if you wish to replace the development token included in map_screen.dart (mapboxAccessToken). The project uses the mapbox/dark-v11 style by default.

1. Clone the repository (private repository):

   Similarly to the backend, the client code is private. Make sure you have the necessary permissions and use your personal token or SSH key to clone. For example:

   git clone https://<user>:<token>@github.com/HEXGO-Studio/HEXGO_frontend.git
   cd HEXGO_frontend

2. Install Flutter dependencies:

   flutter pub get

3. Configure external services:

   • Firebase – register the project in Firebase Console, add Android and iOS apps, and place the configuration files in the android/app and ios/Runner folders accordingly. Follow the firebase_messaging instructions to complete the integration.
   • Mapbox (optional) – if you wish to use your own token, edit the mapboxAccessToken constant in lib/screens/map_screen.dart.
   • Backend link – the SettingsService class defines the API base URL (_prodUrl and _devUrl). In development mode you can set isProduction to false to point to http://10.0.2.2:8000 (Android emulator) or to your backend's local URL. Adjust this value before building the application.

4. Build and run:

   • Android:

     flutter run -d android

• iOS:

     flutter run -d ios

• Web (experimental):

     flutter run -d chrome

5. Advanced options:

   • To generate the app icon and splash screen, the project uses flutter_native_splash. The pubspec.yaml file defines the colours and logo; you can customise them and run flutter pub run flutter_native_splash:create to update the splash screen.
   • Local notifications are configured in notification_service.dart; review that file to customise sounds or actions.

HEXGO's design clearly separates business logic in the backend from the user interface in the frontend. In broad terms:

1. Authentication: the user registers and logs in through the frontend. The backend generates a JWT token that is stored in the device's SharedPreferences. This token is sent in the Authorization header in all subsequent requests.
2. Map and zones: the frontend obtains the GPS location via geolocator, queries /zonas/mapa to receive a list of hexagons and their owner, and draws them on the map with flutter_map. Users can capture zones by sending POST requests to the captures endpoint, which updates the database and generates events in the feed.
3. Ranking and statistics: the application queries /ranking/mi-estado and other ranking endpoints to display the player's points and position. Period and scope filters are converted into query parameters before sending the request.
4. Social feed and notifications: the feed is periodically updated with requests to the /social/feed endpoint based on the active filters. Push notifications are received via Firebase; local ones are scheduled in the backend when a player is inactive.
5. Background services: during a race, a persistent service records the location and calculates distances with a noise filter. Events are communicated to the interface through streams and saved to the database.

1. Pull requests: as these are private repositories, external contributions are subject to prior approval. If you wish to collaborate, contact the development team to gain access and discuss your proposals. In any case, maintain a coding style consistent with PEP 8 in Python and with the analysis rules established in analysis_options.yaml in Flutter.
2. Bug reports: use the issues section of each repository (accessible only to authorised members) to report bugs or propose new features. Include clear steps to reproduce the issue.
3. License and legal notice: at the time of writing this README the repositories do not include an explicit licence file. HEXGO is a trademark registered at the European level, so its commercial use and code distribution are subject to legal restrictions. To contribute or reuse the code in your own projects, contact the owners of HEXGO-Studio to agree on the terms of use and respect the trademark.

This document provides a comprehensive guide to understanding, installing, and running HEXGO. Remember that it is an evolving project; consult the official repositories for the most up-to-date information and participate in the community by contributing improvements and suggestions.