Cloud Notes Mobile

Cloud Notes is a Flutter client for a self-hosted notes server. It provides a clean, Apple Notes-inspired interface for Android and iOS, while keeping notes and authentication data on a server controlled by the user.

Backend repository: reallyShould/Cloud_Notes_API

Features

• configurable self-hosted server address;
• automatic server health check;
• registration and cookie-based authentication;
• secure, persistent server-scoped sessions;
• rich-text note editor with HTML synchronization;
• headings, lists, checklists, links, highlighting and other formatting;
• image attachments loaded through the authenticated API client;
• autosave with local fallback drafts during network failures;
• notes, pinned, favorites and archive sections;
• search and pull-to-refresh;
• automatic background refresh;
• light and dark themes;
• English and Russian interfaces;
• adaptive phone and tablet layouts;
• separate cookies and local drafts for every configured server.

Backend

The mobile application requires a running Cloud Notes API instance:

github.com/reallyShould/Cloud_Notes_API

The backend uses FastAPI, PostgreSQL, HttpOnly JWT cookies, Docker Compose and Nginx. By default, it is available at:

http://SERVER_IP:8080

The mobile application automatically normalizes this address to:

http://SERVER_IP:8080/api

Requirements

• Flutter stable;
• Dart 3.12 or newer;
• Android Studio for Android development;
• Xcode and CocoaPods for iOS development;
• a running Cloud Notes API server.

Getting started

Clone the repository and install dependencies:

git clone <mobile-repository-url>
cd Cloud_Notes_mobile
flutter pub get

Check the development environment:

flutter doctor

Run the application:

flutter run

Server setup

On first launch, enter the LAN address of the computer or home server running the API:

http://192.168.0.100:8080

The application checks:

GET /api/system/health-check

The Continue button becomes available only when the API responds successfully and reports that the database is connected.

Do not enter localhost when running the application on a physical phone. On a phone, localhost refers to the phone itself. The phone and server should normally be connected to the same local network.

The server can later be changed from the login screen or through Settings → Server connection.

Android network configuration

The Android application declares the INTERNET permission and permits cleartext HTTP connections because Cloud Notes is designed to support explicitly configured home servers without a domain or TLS certificate.

HTTPS through a reverse proxy or VPN is recommended when connecting over an untrusted network.

Build a debug APK:

flutter build apk --debug

Build a release APK or Android App Bundle:

flutter build apk --release
flutter build appbundle --release

Release artifacts are written under build/app/outputs/.

iOS network configuration

The iOS runner includes a local-network usage description and ATS configuration for user-selected HTTP servers. For a public or production deployment, use HTTPS and narrow the ATS policy where possible.

Build the iOS application:

flutter build ios --release

An iOS release build requires macOS, Xcode and a configured Apple signing team.

Architecture

lib/
├── app/
│   ├── app_state.dart       # Riverpod application and notes state
│   └── strings.dart         # Centralized interface strings
├── core/
│   ├── api_client.dart      # Dio, CookieJar and secure cookie storage
│   ├── models.dart          # User and note models
│   ├── repositories.dart    # Authentication, notes and attachments API
│   ├── server_address.dart  # Server URL normalization
│   └── storage.dart         # Preferences and server-scoped drafts
├── features/
│   ├── auth/                # Server configuration and authentication
│   ├── notes/               # Notes list and rich-text editor
│   └── settings/            # Server, theme, language and logout
├── l10n/                    # English and Russian ARB resources
└── main.dart                # Application entry point and themes

The main packages used by the project are:

• Riverpod for state management and dependency injection;
• Dio for HTTP requests;
• CookieJar and Flutter Secure Storage for authenticated sessions;
• Flutter Quill for rich-text editing;
• SharedPreferences for server, theme, language and local drafts;
• Image Picker for note attachments.

Data isolation

Cookies and local drafts are scoped by the normalized server URL. Changing the server clears the active session, stops current requests and prevents data from different Cloud Notes installations from being mixed.

Quality checks

Run static analysis and tests before submitting changes:

flutter analyze
flutter test

The test suite covers:

• server URL normalization;
• model serialization;
• repository response handling;
• note filtering;
• theme persistence;
• language persistence.

License

Add the repository license here before publishing or distributing release builds.