How siddharthkarmokar/hooked-app works
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