# siddharthkarmokar/hooked-app architecture

> Architecture diagram of the GitHub repository siddharthkarmokar/hooked-app, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/siddharthkarmokar/hooked-app
- Repository: https://github.com/siddharthkarmokar/hooked-app

## Overview

##### Project Type and Purpose
- Full-stack mobile application with:
– React Native front-end (iOS & Android)
– Python FastAPI back-end
– MongoDB Atlas database
– AI integrations (Perplexity Sonar API, Langchain + Gemini)
– Hosted on AWS (Docker / ECS / S3 / SES)

##### File Structure
- Top-level directories:
– /frontend: React Native code, native projects (android/ios), components, services, navigation, tests.
– /backend: FastAPI app (main.py), routes/, services/, schemas/, configs/, database connectors, static email templates, tests, Dockerfile, ECS task definition.
– /hook-docs: MkDocs site for documentation.
- Notice separation of concerns:
– backend/src/routes: HTTP endpoints (auth, feed, quiz, profile, quest, verify_email)
– backend/src/services: business logic (auth_service, game logic, AI clients)
– backend/src/database & config: connectors to MongoDB, S3, environment settings.
- Deployment & CI:
– Dockerfile, ecs-task-def.json
– GitHub Actions workflows in .github/workflows

##### Relationships & Data Flows
- User Interaction:
– Mobile App ⇄ FastAPI Backend over HTTPS (REST endpoints)
- Backend Logic:
– Routes call Services (e.g., auth_service.py, game.py)
– Services call AI clients (Perplexity & Langchain) and Data Access Layers
- Data Persistence:
– Services use database/mongo.py for CRUD on MongoDB
– Services use s3.py to store/retrieve assets
- Email Verification:
– verify_email route uses utils/verification_email.py → AWS SES
- CI/CD:
– Commits trigger GitHub Actions → build & deploy backend container to ECS, publish docs

##### Architectural Patterns & Principles
- Layered Architecture (Controller → Service → DAO)
- Separation of Concerns (auth, game logic, AI integrations are decoupled)
- Externalize config (common_setting.py, game.py) for environment-specific settings
- Schema validation (Pydantic models in schemas/*)
- Micro-services approach for AI engines (though consolidated in one FastAPI app)
- Infrastructure as Code: ECS task definitions, Dockerfile

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Mobile Application Layer
    subgraph "Mobile Application" 
        direction TB
        MA1["AppNavigator"]:::frontend
        MA2["UI Components"]:::frontend
        MA3["SharedTransitionContext"]:::frontend
        MA4["AuthService"]:::frontend
        MA5["HookService"]:::frontend
        MA6["API Client (api.ts)"]:::frontend
        MA7["Entry Point (App.tsx / index.js)"]:::frontend
    end

    %% API Gateway / Load Balancer
    AGW["API Gateway / AWS ALB"]:::infra

    %% Backend Application Layer
    subgraph "FastAPI Backend" 
        direction TB
        BE0["main.py"]:::backend

        subgraph "Routes / Controllers"
            direction TB
            R1["auth.py"]:::backend
            R2["feed.py"]:::backend
            R3["interaction.py"]:::backend
            R4["profile.py"]:::backend
            R5["quest.py"]:::backend
            R6["verify_email.py"]:::backend
        end

        subgraph "Services / Business Logic"
            direction TB
            S1["auth_service.py"]:::backend
            S2["game.py"]:::backend
            S3["perplexity.py"]:::backend
            S4["gemini.py"]:::backend
            S5["mpad.py"]:::backend
            S6["time_decay.py"]:::backend
        end

        subgraph "Data Layer"
            direction TB
            D1["mongo.py"]:::backend
            D2["s3.py"]:::backend
        end

        subgraph "Utilities & Helpers"
            direction TB
            U1["security.py"]:::backend
            U2["verification_email.py"]:::backend
            U3["common.py"]:::backend
            U4["model.py"]:::backend
        end

        subgraph "Configuration"
            direction TB
            C1["common_setting.py"]:::backend
            C2["game.py (config)"]:::backend
        end

        subgraph "Schemas & Validation"
            direction TB
            SC1["auth_schemas.py"]:::backend
            SC2["profile_schemas.py"]:::backend
            SC3["quiz_schemas.py"]:::backend
            SC4["pplx_schemas.py"]:::backend
            SC5["log_schemas.py"]:::backend
        end

        subgraph "Static Email Templates"
            direction TB
            T1["verify_success.html"]:::backend
            T2["verify_failed.html"]:::backend
        end
    end

    %% Database & Storage
    subgraph "Database & Storage" 
        direction TB
        DB1["MongoDB Atlas"]:::database
        DB2["AWS S3 Bucket"]:::infra
    end

    %% External AI Services
    subgraph "External AI Services"
        direction TB
        AI1["Perplexity Sonar API"]:::external
        AI2["Langchain + Gemini"]:::external
    end

    %% Documentation Site
    Docs["MkDocs Site (hook-docs)"]:::infra

    %% CI/CD
    subgraph "CI/CD & Deployment"
        direction TB
        CI1["GitHub Actions: main.yaml"]:::infra
        CI2["GitHub Actions: docs.yaml"]:::infra
        CI3["Dockerfile"]:::infra
        CI4["ecs-task-def.json"]:::infra
        CI5["ECS Deployment"]:::infra
    end

    %% Connections
    MA7 -->|"HTTPS Requests"| AGW
    AGW -->|"Forwards to"| BE0
    BE0 --> R1
    BE0 --> R2
    BE0 --> R3
    BE0 --> R4
    BE0 --> R5
    BE0 --> R6

    R1 -->|"calls"| S1
    R2 -->|"calls"| S2
    R3 -->|"calls"| S2
    R4 -->|"calls"| S1
    R5 -->|"calls"| S2
    R6 -->|"calls"| U2

    S1 --> D1
    S2 --> D1
    S2 --> D2
    S3 --> AI1
    S4 --> AI2
    S5 --> AI2
    S6 --> D1

    U2 -->|"Sends via SES"| CI2

    CI1 --> CI3
    CI1 --> CI4
    CI3 --> CI5
    CI4 --> CI5

    CI1 -->|"Build Docs"| CI2
    CI2 --> Docs

    D1 -->|"Stores data"| DB1
    D2 -->|"Stores assets"| DB2

    %% Click Events
    click MA1 "https://github.com/siddharthkarmokar/hooked-app/blob/main/frontend/src/navigation/AppNavigator.tsx"
    click MA2 "https://github.com/siddharthkarmokar/hooked-app/tree/main/frontend/src/components/"
    click MA3 "https://github.com/siddharthkarmokar/hooked-app/blob/main/frontend/src/contexts/SharedTransitionContext.tsx"
    click MA4 "https://github.com/siddharthkarmokar/hooked-app/blob/main/frontend/src/services/AuthService.ts"
    click MA5 "https://github.com/siddharthkarmokar/hooked-app/blob/main/frontend/src/services/HookService.ts"
    click MA6 "https://github.com/siddharthkarmokar/hooked-app/blob/main/frontend/src/services/api.ts"
    click MA7 "https://github.com/siddharthkarmokar/hooked-app/blob/main/frontend/App.tsx"
    click MA7 "https://github.com/siddharthkarmokar/hooked-app/blob/main/frontend/index.js"
    click AGW "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/ecs-task-def.json"
    click CI3 "https://github.com/siddharthkarmokar/hooked-app/tree/main/backend/Dockerfile"
    click BE0 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/main.py"
    click R1 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/routes/auth.py"
    click R2 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/routes/feed.py"
    click R3 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/routes/interaction.py"
    click R4 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/routes/profile.py"
    click R5 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/routes/quest.py"
    click R6 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/routes/verify_email.py"
    click S1 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/services/auth_service.py"
    click S2 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/services/game.py"
    click S3 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/services/perplexity.py"
    click S4 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/services/gemini.py"
    click S5 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/services/mpad.py"
    click S6 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/services/time_decay.py"
    click D1 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/database/mongo.py"
    click D2 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/database/s3.py"
    click U1 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/utils/security.py"
    click U2 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/utils/verification_email.py"
    click U3 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/utils/common.py"
    click U4 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/utils/model.py"
    click C1 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/config/common_setting.py"
    click C2 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/config/game.py"
    click SC1 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/schemas/auth_schemas.py"
    click SC2 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/schemas/profile_schemas.py"
    click SC3 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/schemas/quiz_schemas.py"
    click SC4 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/schemas/pplx_schemas.py"
    click SC5 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/src/schemas/log_schemas.py"
    click T1 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/static/verify_success.html"
    click T2 "https://github.com/siddharthkarmokar/hooked-app/blob/main/backend/static/verify_failed.html"
    click Docs "https://github.com/siddharthkarmokar/hooked-app/tree/main/hook-docs/"
    click Docs "https://github.com/siddharthkarmokar/hooked-app/blob/main/hook-docs/mkdocs.yml"
    click CI1 "https://github.com/siddharthkarmokar/hooked-app/blob/main/.github/workflows/main.yaml"
    click CI2 "https://github.com/siddharthkarmokar/hooked-app/blob/main/.github/workflows/docs.yaml"

    %% Styles
    classDef frontend fill:#AED6F1,stroke:#1F618D,stroke-width:2px
    classDef backend fill:#ABEBC6,stroke:#196F3D,stroke-width:2px
    classDef external fill:#F9E79F,stroke:#B9770E,stroke-width:2px
    classDef database fill:#D5D8DC,stroke:#626567,stroke-width:2px
    classDef infra fill:#E5E8E8,stroke:#707B7C,stroke-width:2px
```
