# Architecture guardrails

## Proposed stack

- Kotlin
- Jetpack Compose and Material 3
- Coroutines and Flow
- Hilt for dependency injection
- Retrofit/OkHttp or Ktor Client, selected once in an ADR
- Room only when offline caching is approved
- AndroidX Browser/AppAuth-compatible system-browser OAuth flow

## Layers

```text
UI (Compose)
  -> presentation state and events
  -> domain use cases and models
  -> repository interfaces
  -> data implementations
  -> Gitea HTTP API / secure local storage
```

Dependencies point inward. DTOs, HTTP clients, Android contexts, and persistence entities do not leak into domain models.

## Initial module strategy

Begin with one application module and package by feature. Split Gradle modules only when build time or ownership boundaries justify the added complexity.

```text
app/
  core/auth
  core/network
  core/designsystem
  feature/login
  feature/repositories
  feature/issues
  feature/pullrequests
  feature/notifications
```

## Configuration

Production defaults may contain the public Gitea URL and OAuth client ID. Environment-specific values must be injectable for tests. Client secrets and signing material must never be committed.

## Architecture decisions

Material choices belong in `docs/decisions/` as short ADRs stating context, decision, alternatives, and consequences.