# dos-ajith/native-life-dev architecture

> Architecture diagram of the GitHub repository dos-ajith/native-life-dev, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-10-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/dos-ajith/native-life-dev
- Repository: https://github.com/dos-ajith/native-life-dev

## Overview

Native Life API is a modular-monolith backend for the mobile app and web admin panel. A typical request enters a versioned FastAPI route, is validated and authorized, runs domain logic, and persists through repositories and SQLAlchemy models to PostgreSQL. Major capabilities include authentication and administration, posts and social interactions, collections, geography, notifications, pages, and user settings. The AI endpoint is a distinct read-only workflow that delegates tool requests to existing services and an external provider. Unsampled modules are included where documented; their internal calls are not inferred.

Main entry points: [`app/api/v1/router.py`](https://github.com/dos-ajith/native-life-dev/blob/main/app/api/v1/router.py) (API Router), [`app/api/v1/posts/routes.py`](https://github.com/dos-ajith/native-life-dev/blob/main/app/api/v1/posts/routes.py) (Posts API), [`app/ai/service.py`](https://github.com/dos-ajith/native-life-dev/blob/main/app/ai/service.py) (AI Orchestrator), [`app/repositories`](https://github.com/dos-ajith/native-life-dev/tree/main/app/repositories) (Repositories)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_api["HTTP API"]
  node_router["API Router<br/>[router.py]"]
  node_auth_api["Authentication API<br/>[routes.py]"]
  node_posts_api["Posts API<br/>[routes.py]"]
  node_social_api["Social APIs"]
  node_collections_api["Collections API<br/>[routes.py]"]
  node_geography_api["Geography API<br/>[routes.py]"]
  node_settings_api["User Settings API<br/>[routes.py]"]
  node_admin_api["Admin APIs<br/>[routes.py]"]
  node_ai_api["AI API<br/>[routes.py]"]
end

subgraph group_domain["Domain Services"]
  node_auth_service["Authentication Service<br/>[auth_service.py]"]
  node_post_service["Post Service<br/>[post_service.py]"]
  node_geography_service["Geography Services"]
  node_geography_import["Geography Import"]
  node_user_service["User Service<br/>[user_service.py]"]
  node_user_settings["Settings Service"]
end

subgraph group_ai["AI Integration"]
  node_ai_service["AI Orchestrator<br/>[service.py]"]
  node_ai_tools["Read-only Tools"]
  node_ai_client["Provider Client<br/>[client.py]"]
  node_provider(("AI Provider"))
end

subgraph group_shared["Shared and Persistence"]
  node_main["Application Entry<br/>[main.py]"]
  node_deps["Auth and Request Dependencies<br/>[deps.py]"]
  node_activity["Activity Logging"]
  node_repositories["Repositories"]
  node_models["ORM Models"]
  node_database[("PostgreSQL")]
end

node_clients(("App and Admin Clients"))

node_clients -->|"sends requests"| node_router
node_main -->|"mounts"| node_router
node_router -.->|"routes to"| node_auth_api
node_router -.->|"routes to"| node_posts_api
node_router -.->|"routes to"| node_collections_api
node_router -.->|"routes to"| node_geography_api
node_router -.->|"routes to"| node_settings_api
node_router -.->|"routes to"| node_admin_api
node_router -.->|"routes to"| node_ai_api
node_auth_api -.->|"delegates to"| node_auth_service
node_auth_service -->|"queries"| node_repositories
node_posts_api -->|"calls"| node_post_service
node_posts_api -.->|"includes operations"| node_social_api
node_collections_api -.->|"uses services"| node_repositories
node_geography_api -->|"calls"| node_geography_service
node_geography_import -->|"logs activity"| node_activity
node_admin_api -->|"calls"| node_user_service
node_settings_api -->|"calls"| node_user_settings
node_user_settings -->|"logs changes"| node_activity
node_ai_api -.->|"delegates to"| node_ai_service
node_ai_service -->|"requests completion"| node_ai_client
node_ai_service -->|"dispatches tools"| node_ai_tools
node_ai_tools -.->|"calls services"| node_post_service
node_ai_client -->|"sends prompts"| node_provider
node_repositories -->|"queries and persists"| node_models
node_models -->|"maps to"| node_database

click node_main "https://github.com/dos-ajith/native-life-dev/blob/main/app/main.py"
click node_router "https://github.com/dos-ajith/native-life-dev/blob/main/app/api/v1/router.py"
click node_auth_api "https://github.com/dos-ajith/native-life-dev/blob/main/app/api/v1/auth/routes.py"
click node_posts_api "https://github.com/dos-ajith/native-life-dev/blob/main/app/api/v1/posts/routes.py"
click node_social_api "https://github.com/dos-ajith/native-life-dev/tree/main/app/api/v1/posts"
click node_collections_api "https://github.com/dos-ajith/native-life-dev/blob/main/app/api/v1/collections/routes.py"
click node_geography_api "https://github.com/dos-ajith/native-life-dev/blob/main/app/api/v1/geography/routes.py"
click node_settings_api "https://github.com/dos-ajith/native-life-dev/blob/main/app/api/v1/user_settings/routes.py"
click node_admin_api "https://github.com/dos-ajith/native-life-dev/blob/main/app/api/v1/admin/routes.py"
click node_ai_api "https://github.com/dos-ajith/native-life-dev/blob/main/app/api/v1/ai/routes.py"
click node_auth_service "https://github.com/dos-ajith/native-life-dev/blob/main/app/services/auth_service.py"
click node_post_service "https://github.com/dos-ajith/native-life-dev/blob/main/app/services/post_service.py"
click node_geography_service "https://github.com/dos-ajith/native-life-dev/blob/main/app/services/geography_service.py"
click node_geography_import "https://github.com/dos-ajith/native-life-dev/blob/main/app/services/geography_import_service.py"
click node_user_service "https://github.com/dos-ajith/native-life-dev/blob/main/app/services/user_service.py"
click node_user_settings "https://github.com/dos-ajith/native-life-dev/blob/main/app/services/user_settings_service.py"
click node_ai_service "https://github.com/dos-ajith/native-life-dev/blob/main/app/ai/service.py"
click node_ai_tools "https://github.com/dos-ajith/native-life-dev/tree/main/app/ai/tools"
click node_ai_client "https://github.com/dos-ajith/native-life-dev/blob/main/app/ai/client.py"
click node_deps "https://github.com/dos-ajith/native-life-dev/blob/main/app/api/deps.py"
click node_activity "https://github.com/dos-ajith/native-life-dev/blob/main/app/services/activity_log_service.py"
click node_repositories "https://github.com/dos-ajith/native-life-dev/tree/main/app/repositories"
click node_models "https://github.com/dos-ajith/native-life-dev/tree/main/app/models"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_router,node_auth_api,node_posts_api,node_social_api,node_collections_api,node_geography_api,node_settings_api,node_admin_api,node_ai_api,node_clients toneBlue
class node_auth_service,node_post_service,node_geography_service,node_geography_import,node_user_service,node_user_settings toneAmber
class node_ai_service,node_ai_tools,node_ai_client,node_provider toneMint
class node_main,node_deps,node_activity,node_repositories,node_models,node_database toneRose
```

## Components

### HTTP API

- [API Router](https://github.com/dos-ajith/native-life-dev/blob/main/app/api/v1/router.py): `app/api/v1/router.py`
- [Authentication API](https://github.com/dos-ajith/native-life-dev/blob/main/app/api/v1/auth/routes.py): `app/api/v1/auth/routes.py`
- [Posts API](https://github.com/dos-ajith/native-life-dev/blob/main/app/api/v1/posts/routes.py): `app/api/v1/posts/routes.py`
- [Social APIs](https://github.com/dos-ajith/native-life-dev/tree/main/app/api/v1/posts): `app/api/v1/posts`
- [Collections API](https://github.com/dos-ajith/native-life-dev/blob/main/app/api/v1/collections/routes.py): `app/api/v1/collections/routes.py`
- [Geography API](https://github.com/dos-ajith/native-life-dev/blob/main/app/api/v1/geography/routes.py): `app/api/v1/geography/routes.py`
- [User Settings API](https://github.com/dos-ajith/native-life-dev/blob/main/app/api/v1/user_settings/routes.py): `app/api/v1/user_settings/routes.py`
- [Admin APIs](https://github.com/dos-ajith/native-life-dev/blob/main/app/api/v1/admin/routes.py): `app/api/v1/admin/routes.py`
- [AI API](https://github.com/dos-ajith/native-life-dev/blob/main/app/api/v1/ai/routes.py): `app/api/v1/ai/routes.py`

### Domain Services

- [Authentication Service](https://github.com/dos-ajith/native-life-dev/blob/main/app/services/auth_service.py): `app/services/auth_service.py`
- [Post Service](https://github.com/dos-ajith/native-life-dev/blob/main/app/services/post_service.py): `app/services/post_service.py`
- [Geography Services](https://github.com/dos-ajith/native-life-dev/blob/main/app/services/geography_service.py): `app/services/geography_service.py`
- [Geography Import](https://github.com/dos-ajith/native-life-dev/blob/main/app/services/geography_import_service.py): `app/services/geography_import_service.py`
- [User Service](https://github.com/dos-ajith/native-life-dev/blob/main/app/services/user_service.py): `app/services/user_service.py`
- [Settings Service](https://github.com/dos-ajith/native-life-dev/blob/main/app/services/user_settings_service.py): `app/services/user_settings_service.py`

### AI Integration

- [AI Orchestrator](https://github.com/dos-ajith/native-life-dev/blob/main/app/ai/service.py): `app/ai/service.py`
- [Read-only Tools](https://github.com/dos-ajith/native-life-dev/tree/main/app/ai/tools): `app/ai/tools`
- [Provider Client](https://github.com/dos-ajith/native-life-dev/blob/main/app/ai/client.py): `app/ai/client.py`
- **AI Provider**

### Shared and Persistence

- [Application Entry](https://github.com/dos-ajith/native-life-dev/blob/main/app/main.py): `app/main.py`
- [Auth and Request Dependencies](https://github.com/dos-ajith/native-life-dev/blob/main/app/api/deps.py): `app/api/deps.py`
- [Activity Logging](https://github.com/dos-ajith/native-life-dev/blob/main/app/services/activity_log_service.py): `app/services/activity_log_service.py`
- [Repositories](https://github.com/dos-ajith/native-life-dev/tree/main/app/repositories): `app/repositories`
- [ORM Models](https://github.com/dos-ajith/native-life-dev/tree/main/app/models): `app/models`
- **PostgreSQL**

### Other components

- **App and Admin Clients**

## Connections

- App and Admin Clients → API Router: sends requests
- Application Entry → API Router: mounts (evidence: `app/main.py`)
- API Router → Authentication API: routes to
- API Router → Posts API: routes to
- API Router → Collections API: routes to
- API Router → Geography API: routes to
- API Router → User Settings API: routes to
- API Router → Admin APIs: routes to
- API Router → AI API: routes to
- Authentication API → Authentication Service: delegates to
- Authentication Service → Repositories: queries (evidence: `app/services/auth_service.py`)
- Posts API → Post Service: calls (evidence: `app/api/v1/posts/routes.py`)
- Posts API → Social APIs: includes operations (evidence: `app/api/v1/posts/routes.py`)
- Collections API → Repositories: uses services
- Geography API → Geography Services: calls (evidence: `app/api/v1/geography/routes.py`)
- Geography Import → Activity Logging: logs activity (evidence: `app/services/geography_import_service.py`)
- Admin APIs → User Service: calls (evidence: `app/api/v1/admin/routes.py`)
- User Settings API → Settings Service: calls (evidence: `app/api/v1/user_settings/routes.py`)
- Settings Service → Activity Logging: logs changes (evidence: `app/services/user_settings_service.py`)
- AI API → AI Orchestrator: delegates to
- AI Orchestrator → Provider Client: requests completion (evidence: `app/ai/service.py`)
- AI Orchestrator → Read-only Tools: dispatches tools (evidence: `app/ai/service.py`)
- Read-only Tools → Post Service: calls services
- Provider Client → AI Provider: sends prompts (evidence: `app/ai/client.py`)
- Repositories → ORM Models: queries and persists (evidence: `app/repositories/post_repository.py`)
- ORM Models → PostgreSQL: maps to
