MyActivityPub/README.md

# My ActivityPub

A modern Android client for ActivityPub and Mastodon instances built with Jetpack Compose.

## Overview

My ActivityPub is a beautiful, user-friendly Android application that allows you to interact with Mastodon and other ActivityPub-compatible social networks. The app features a clean, modern UI built entirely with Jetpack Compose and Material Design 3.

## Features

### Core Features
- 📱 **Modern Material Design 3 UI** - Beautiful, responsive interface
- 🌐 **Multi-Instance Support** - Connect to any Mastodon/ActivityPub instance
- 🔐 **OAuth Authentication** - Secure login with OAuth 2.0
- 📰 **Public & Home Timelines** - Browse federated and personal timelines
- 🔄 **Pull-to-Refresh** - Swipe down to update your timeline
- ⚡ **Auto-Refresh** - Timeline automatically updates every 30 seconds
- 🔗 **Interactive Links & Hashtags** - Click URLs and hashtags in posts
- 🖼️ **Media Attachments** - View images and media in posts
- 💬 **Post Interactions** - Reply, boost, and favorite posts
- 📊 **Status Details** - View full posts with reply threads
- 🔔 **Notifications** - Stay updated with mentions and interactions
- ♾️ **Infinite Scrolling** - Load more posts as you scroll
- 🎨 **Dynamic Colors** - Adapts to your system theme (Android 12+)
- 🌙 **Dark Mode** - Full dark theme support

## Screenshots

(Coming soon)

## Tech Stack

- **Language**: Kotlin
- **UI Framework**: Jetpack Compose
- **Architecture**: MVVM (Model-View-ViewModel)
- **Networking**: Retrofit 2 + OkHttp
- **Image Loading**: Coil
- **Async Operations**: Kotlin Coroutines + Flow
- **Material Design**: Material 3

## Project Structure

```
app/
├── src/main/java/com/manalejandro/myactivitypub/
│   ├── MainActivity.kt                      # Main entry point
│   ├── data/
│   │   ├── api/
│   │   │   └── MastodonApiService.kt       # API service interface
│   │   ├── models/
│   │   │   ├── Account.kt                  # User account model
│   │   │   ├── Status.kt                   # Post/status model
│   │   │   ├── MediaAttachment.kt          # Media attachment model
│   │   │   └── Instance.kt                 # Instance information model
│   │   └── repository/
│   │       └── MastodonRepository.kt       # Data repository
│   └── ui/
│       ├── components/
│       │   └── StatusCard.kt               # Status card component
│       ├── viewmodel/
│       │   └── TimelineViewModel.kt        # Timeline view model
│       └── theme/
│           ├── Color.kt                    # Color definitions
│           ├── Theme.kt                    # Theme configuration
│           └── Type.kt                     # Typography
```

## Architecture

The app follows the MVVM (Model-View-ViewModel) architecture pattern:

- **Model**: Data classes representing API responses (`Status`, `Account`, etc.)
- **View**: Composable functions for UI (`StatusCard`, `MyActivityPubApp`)
- **ViewModel**: `TimelineViewModel` manages UI state and business logic
- **Repository**: `MastodonRepository` handles data operations and API calls

### Data Flow

```
API Service → Repository → ViewModel → UI State → Composable UI
```

## Getting Started

### Prerequisites

- Android Studio Hedgehog (2023.1.1) or newer
- JDK 11 or higher
- Android SDK with API level 24+ (Android 7.0+)

### Building the Project

1. Clone the repository:
```bash
git clone <repository-url>
cd MyActivityPub
```

2. Open the project in Android Studio

3. Sync Gradle files

4. Build and run:
```bash
./gradlew assembleDebug
```

The APK will be generated at:
```
app/build/outputs/apk/debug/app-debug.apk
```

### Running on Device/Emulator

1. Connect your Android device or start an emulator
2. Click "Run" in Android Studio or use:
```bash
./gradlew installDebug
```

## API Reference

The app uses the Mastodon API v1 specification. By default, it connects to `mastodon.social`, but you can modify the base URL in `MainActivity.kt`.

### Supported Endpoints

- `GET /api/v1/timelines/public` - Fetch public timeline
- `GET /api/v1/instance` - Get instance information
- `GET /api/v1/accounts/:id` - Get account details
- `GET /api/v1/accounts/:id/statuses` - Get account statuses

For more information, see the [Mastodon API documentation](https://docs.joinmastodon.org/api/).

## Configuration

### Changing the Instance

To connect to a different Mastodon instance, modify the base URL in `MainActivity.kt`:

```kotlin
val retrofit = Retrofit.Builder()
    .baseUrl("https://your-instance.social/")
    // ...
```

### Gradle Configuration

Key configuration files:
- `build.gradle.kts` - App dependencies and build configuration
- `gradle.properties` - Gradle properties (JVM memory, etc.)
- `libs.versions.toml` - Version catalog for dependencies

## Dependencies

| Library | Version | Purpose |
|---------|---------|---------|
| Retrofit | 2.9.0 | REST API client |
| OkHttp | 4.12.0 | HTTP client |
| Gson | 2.9.0 | JSON serialization |
| Coil | 2.5.0 | Image loading |
| Coroutines | 1.7.3 | Async programming |
| Compose BOM | 2024.09.00 | Jetpack Compose libraries |
| Material 3 | Latest | Material Design 3 components |

## Development

### Code Style

This project follows the official Kotlin coding conventions. Key guidelines:

- Use 4 spaces for indentation
- Use camelCase for variables and functions
- Use PascalCase for classes
- Add KDoc comments for public APIs
- Keep functions small and focused

### Adding New Features

1. Create data models in `data/models/`
2. Add API endpoints in `MastodonApiService.kt`
3. Implement repository methods in `MastodonRepository.kt`
4. Create ViewModel with UI state in `ui/viewmodel/`
5. Build UI components in `ui/components/`
6. Wire everything together in composable screens

## Troubleshooting

### Build Issues

**Gradle daemon crashes:**
- Increase JVM memory in `gradle.properties`: `org.gradle.jvmargs=-Xmx4096m`

**Dependency resolution fails:**
- Clear Gradle cache: `./gradlew clean --no-daemon`
- Invalidate caches in Android Studio

**Compose compiler issues:**
- Ensure Kotlin and Compose versions are compatible
- Check `libs.versions.toml` for version alignment

### Runtime Issues

**Network errors:**
- Verify `INTERNET` permission in `AndroidManifest.xml`
- Check device/emulator internet connection
- Ensure HTTPS URLs are used (clear text traffic is disabled)

**Image loading failures:**
- Coil requires valid URLs
- Check LogCat for detailed error messages

## Recent Updates

### Latest Features (v1.0)

#### 🔄 Pull-to-Refresh
The app now supports pull-to-refresh functionality on all timelines. Simply swipe down from the top of the timeline to fetch the latest posts from your instance.

#### ⚡ Automatic Timeline Updates
Timelines now automatically check for new posts every 30 seconds. New posts appear seamlessly at the top of your timeline without interrupting your reading experience.

**How it works:**
- Background coroutine checks for new posts using `since_id` parameter
- Updates are silent and don't interfere with scrolling
- Auto-refresh restarts when switching between timelines
- Minimal network usage - only fetches posts newer than the current top post

#### 🔗 Interactive Content
Post content is now fully interactive with support for:
- **Clickable URLs**: Tap any link to open in your default browser
- **Hashtags**: Styled and clickable hashtags
- **Rich HTML content**: Proper rendering of formatted text

All links and hashtags are displayed in your theme's primary color with underlines for easy identification.

For detailed information about all features, see [FEATURES.md](docs/FEATURES.md).

## Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see the LICENSE file for details.

## Acknowledgments

- [Mastodon](https://joinmastodon.org/) for the API specification
- [Takahe](https://github.com/jointakahe/takahe) for API reference
- Material Design 3 for the beautiful design system
- The Android and Kotlin communities

## Contact

For questions or feedback, please open an issue on GitHub.

---

**Note**: This is a demonstration project showcasing modern Android development with Jetpack Compose. For production use, consider adding authentication, error handling improvements, and additional features like posting, following, and notifications.