init

.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+env/
+venv/
+.venv/
+.idea/
+*.log
+*.egg-info/
+pip-wheel-EntityData/
+.env
+.DS_Store
+static/
+test.py
+rsa_key.p8
+rsa_key.pub
+aws.pem
+.vscode/
+data/
+*.csv
+test.json
+voiceagentcbh.pem
+*.pem
+download

WeeklyProgress.md

@@ -0,0 +1,56 @@
+# Weekly Progress Report - Backend Development
+
+## Project Overview
+Successfully initiated and advanced the backend development for ClipboardHealthAI, a health and fitness platform connecting coaches with users through scheduled calls and training sessions.
+
+## Major Accomplishments
+
+### 1. **Core Infrastructure Setup**
+- **FastAPI Framework**: Implemented a robust FastAPI application with proper middleware configuration
+- **Database Layer**: Established MongoDB integration with custom Pydantic models for seamless data serialization
+- **Authentication System**: Built comprehensive JWT-based authentication with role-based access control
+- **Error Handling**: Implemented standardized response wrappers and exception handling
+
+### 2. **User Management System**
+- **Complete CRUD Operations**: Full account management including creation, retrieval, updates, and deletion
+- **Role-Based Permissions**: Implemented ADMIN, USER, and COACH user types with appropriate access controls
+- **Profile Management**: Added profile picture upload functionality with S3 integration
+- **User Registration & Login**: Secure authentication endpoints with token generation and verification
+
+### 3. **Call Scheduling & Payment Integration**
+- **Stripe Integration**: Implemented payment processing for call bookings with webhook handling
+- **Call Management**: Built call creation and management system linking coaches and users
+- **Event System**: Developed event creation functionality for scheduling training sessions
+
+### 4. **Coach Availability System**
+- **Time Slot Management**: Implemented coach availability tracking and management
+- **Availability Queries**: Built endpoints for retrieving coach schedules for users and admins
+- **Coach-Specific Features**: Role-based availability updates restricted to coach accounts
+
+### 5. **Supporting Infrastructure**
+- **File Storage**: Integrated AWS S3 for secure profile picture storage
+- **Timezone Support**: Added timezone search functionality for global user support
+- **Health Monitoring**: Implemented health check endpoints for system monitoring
+- **CORS Configuration**: Configured cross-origin resource sharing for frontend integration
+
+## Technical Implementation Highlights
+
+- **Modular Architecture**: Clean separation of concerns with dedicated modules for each domain (account, calls, availability, security, events)
+- **Database Design**: Custom MongoDB models with proper serialization and enum handling
+- **Security**: Comprehensive permission system with dependency injection for endpoint protection
+- **Payment Processing**: Production-ready Stripe integration with webhook verification
+- **API Design**: RESTful endpoints with consistent request/response patterns
+
+## System Capabilities Delivered
+
+✅ User registration and authentication  
+✅ Account management with profile pictures  
+✅ Role-based access control (Admin/User/Coach)  
+✅ Coach availability management  
+✅ Call booking system with Stripe payments  
+✅ Event scheduling functionality  
+✅ Timezone support for global users  
+✅ File upload and storage integration  
+✅ Health monitoring and error handling  
+
+The backend foundation is now established with core business logic implemented and ready for frontend integration and further feature development.

cbh/__init__.py

@@ -0,0 +1,74 @@
+# pylint: disable=C0415
+"""
+ClipboardHealthAI application package.
+"""
+import asyncio
+
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+from starlette.exceptions import HTTPException as StarletteHTTPException
+
+from cbh.core.wrappers import CbhResponseWrapper, ErrorCbhResponse
+
+
+def create_app() -> FastAPI:
+    """
+    Create and configure the FastAPI application.
+    """
+    app = FastAPI(docs_url="/api/docs", openapi_url="/api/openapi.json")
+
+    from cbh.api.account import account_router
+
+    app.include_router(account_router, tags=["account"])
+
+    from cbh.api.availability import availability_router
+
+    app.include_router(availability_router, tags=["availability"])
+
+    from cbh.api.calls import calls_router
+
+    app.include_router(calls_router, tags=["calls"])
+
+    from cbh.api.security import security_router
+
+    app.include_router(security_router, tags=["security"])
+
+    # TODO написать скрипт миграци сценариев
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origin_regex=r"https?://([a-z0-9-]+\.)?(localhost|trainwitharena|cbhexp\.com)(:\d+)?",
+        allow_credentials=True,
+        allow_methods=["*"],
+        allow_headers=["*"],
+    )
+
+    @app.exception_handler(StarletteHTTPException)
+    async def http_exception_handler(_, exc):
+        """
+        Handle HTTP exceptions and convert them to standardized error responses.
+        """
+        return CbhResponseWrapper(
+            data=None, successful=False, error=ErrorCbhResponse(message=str(exc.detail))
+        ).response(exc.status_code)
+
+    @app.on_event("startup")
+    async def startup_event():
+        """
+        Execute startup tasks when the application starts.
+        """
+
+    @app.get("/api/health")
+    async def health():
+        """
+        Health check endpoint for container orchestration and monitoring.
+        """
+        return {"status": "healthy"}
+
+    @app.get("/")
+    async def root():
+        """
+        Root endpoint for the application.
+        """
+        return {"message": "hi!"}
+
+    return app

cbh/api/account/__init__.py

@@ -0,0 +1,14 @@
+"""
+Account module initialization.
+
+This module defines the FastAPI router for account API endpoints
+and imports related views for account management.
+"""
+
+from fastapi import APIRouter
+
+account_router = APIRouter(
+    prefix="/api/account",
+)
+
+from . import views  # noqa # pylint: disable=C0413

cbh/api/account/db_requests.py

@@ -0,0 +1,76 @@
+"""
+Account database requests.
+"""
+
+import asyncio
+from datetime import datetime
+import re
+from cbh.api.account.models import AccountModel
+from cbh.api.account.schemas import AccountFilter, UpdateAccountRequest, AccountResponse
+from cbh.api.account.dto import AccountType
+from cbh.api.account.utils import (
+    add_teams_session_reports_to_accounts,
+    prepare_additional_filter,
+)
+from cbh.api.common.db_requests import get_all_objs, get_obj_by_id
+from cbh.api.common.schemas import FilterRequest
+from cbh.core.config import settings
+
+
+async def update_own_account_obj(
+    request: UpdateAccountRequest, account: AccountModel
+) -> AccountModel:
+    """
+    Update own account.
+    """
+    account.name = request.name
+    account.email = request.email
+    account.datetimeUpdated = datetime.now()
+    await settings.DB_CLIENT.accounts.update_one(
+        {"id": account.id},
+        {"$set": account.to_mongo()},
+    )
+    return account
+
+
+async def update_account_picture_obj(
+    account: AccountModel, picture_s3: str
+) -> AccountModel:
+    """
+    Update account picture.
+    """
+    account.pictureUrl = picture_s3
+    account.datetimeUpdated = datetime.now()
+    await settings.DB_CLIENT.accounts.update_one(
+        {"id": account.id}, {"$set": account.to_mongo()}
+    )
+    return AccountModel(**account.to_mongo())
+
+
+async def filter_accounts_objs(
+    account: AccountModel, request: FilterRequest[AccountFilter]
+) -> tuple[list[AccountModel], int]:
+    """
+    Filter accounts.
+    """
+    filters = prepare_additional_filter(account)
+    if request.filter.accountTypes:
+        filters["accountType"] = {"$in": request.filter.accountTypes}
+    if request.filter.searchTerm:
+        content = f"^{re.escape(request.filter.searchTerm)}"
+        filters["$or"] = [
+            {"name": {"$regex": content, "$options": "i"}},
+            {"email": {"$regex": content, "$options": "i"}},
+        ]
+    if request.sortBy:
+        sort = (request.sortBy.name, request.sortBy.order.value)
+    else:
+        sort = ("id", -1)
+    accounts, total_count = await get_all_objs(
+        AccountModel,
+        request.pageSize,
+        request.pageIndex,
+        additional_filter=filters,
+        sort=sort,
+    )
+    return accounts, total_count

cbh/api/account/dto.py

@@ -0,0 +1,25 @@
+"""
+Account DTOs.
+"""
+
+from enum import Enum
+
+
+class AccountType(Enum):
+    """
+    Enum for account types.
+    """
+
+    USER = 1
+    COACH = 2
+    ADMIN = 3
+
+
+class AccountStatus(Enum):
+    """
+    Enum for account statuses.
+    """
+
+    ACTIVE = 1
+    BLOCKED = 2
+    PENDING_INVITATION = 3

cbh/api/account/models.py

@@ -0,0 +1,69 @@
+"""
+Account models.
+"""
+
+from datetime import datetime
+
+from passlib.context import CryptContext
+from pydantic import Field, field_validator
+
+from cbh.api.account.dto import AccountStatus, AccountType
+from cbh.core.database import MongoBaseModel, MongoBaseShortenModel
+
+
+class AccountModel(MongoBaseModel):
+    """
+    Account model class.
+
+    This class represents a user account in the system.
+    It includes fields for email, password, and timestamps for creation and update.
+    """
+
+    name: str | None = None
+    email: str
+    pictureUrl: str | None = None
+    password: str | None = Field(exclude=True, default=None)
+
+    status: AccountStatus = AccountStatus.ACTIVE
+    accountType: AccountType = Field(default=AccountType.USER)
+
+    datetimeInserted: datetime = Field(default_factory=datetime.now)
+    datetimeUpdated: datetime = Field(default_factory=datetime.now)
+
+    @field_validator("password", mode="before", check_fields=False)
+    @classmethod
+    def set_password_hash(cls, v: str | None) -> str | None:
+        """
+        Set the password hash.
+
+        Args:
+            v (str): The password to hash.
+
+        Returns:
+            str: The hashed password.
+        """
+        if isinstance(v, str) and not v.startswith("$2b$"):
+            return CryptContext(schemes=["bcrypt"], deprecated="auto").hash(v)
+        return v
+
+    class Config:  # pylint: disable=R0903
+        """
+        Config for the AccountModel class.
+        """
+
+        arbitrary_types_allowed = True
+        populate_by_name = True
+        json_encoders = {datetime: lambda dt: dt.isoformat()}
+
+
+class AccountShorten(MongoBaseShortenModel):
+    """
+    Account shorten model.
+    """
+
+    id: str
+    name: str | None = None
+    email: str
+    pictureUrl: str | None = None
+
+    accountType: AccountType

cbh/api/account/schemas.py

@@ -0,0 +1,21 @@
+from pydantic import BaseModel
+
+from cbh.api.account.models import AccountModel
+
+
+class UpdateAccountRequest(BaseModel):
+    """
+    Update account request.
+    """
+
+    name: str
+    email: str
+
+
+class AccountFilter(BaseModel):
+    """
+    Account filter.
+    """
+
+    accountTypes: list[int] | None = None
+    searchTerm: str | None = None

cbh/api/account/utils.py

@@ -0,0 +1,28 @@
+from io import BytesIO
+
+from PIL import Image, ImageOps, UnidentifiedImageError
+from fastapi import HTTPException, UploadFile
+
+
+def compress_image(file: UploadFile) -> bytes:
+    if not file.content_type or not file.content_type.startswith("image/"):
+        raise HTTPException(status_code=400, detail="File must be an image")
+    try:
+        file.file.seek(0)
+        original_bytes = file.file.read()
+        image = Image.open(BytesIO(original_bytes))
+        image = ImageOps.exif_transpose(image)
+        max_size = 512
+        image.thumbnail((max_size, max_size), Image.Resampling.LANCZOS)
+        if image.mode not in ("RGB", "RGBA"):
+            image = image.convert("RGBA")
+        buffer = BytesIO()
+        image.save(buffer, format="PNG", optimize=True, compress_level=9)
+        return buffer.getvalue()
+    except (UnidentifiedImageError, OSError):
+        raise HTTPException(status_code=400, detail="Invalid image file")
+    finally:
+        try:
+            file.file.close()
+        except Exception:
+            pass

cbh/api/account/views.py

@@ -0,0 +1,188 @@
+"""
+Account views module.
+"""
+
+from fastapi import Depends, File, Query, UploadFile
+
+from cbh.api.account import account_router
+from cbh.api.account.db_requests import (
+    filter_accounts_objs,
+    update_account_picture_obj,
+    update_own_account_obj,
+)
+from cbh.api.account.dto import AccountType
+from cbh.api.account.models import AccountModel
+from cbh.api.account.schemas import (
+    AccountFilter,
+    UpdateAccountRequest,
+)
+from cbh.api.account.utils import compress_image, prepare_additional_filter
+from cbh.api.common.db_requests import (
+    get_all_objs,
+    get_obj_by_id,
+    delete_obj,
+    search_objs,
+)
+from cbh.api.common.dto import Paging
+from cbh.api.common.schemas import AllObjectsResponse, FilterRequest, SearchRequest
+from cbh.core.config import settings
+from cbh.core.security import PermissionDependency
+from cbh.core.wrappers import CbhResponseWrapper
+
+
+@account_router.get("/all")
+async def get_all_accounts(
+    pageSize: int = Query(  # pylint: disable=C0103
+        default=10, ge=0, le=100, description="The number of accounts to return"
+    ),
+    pageIndex: int = Query(  # pylint: disable=C0103
+        default=0, ge=0, description="The page number to return"
+    ),
+    account: AccountModel = Depends(PermissionDependency([AccountType.ADMIN])),
+) -> CbhResponseWrapper[AllObjectsResponse[AccountModel]]:
+    """
+    Get all accounts.
+    """
+    filter_ = prepare_additional_filter(account)
+    accounts, total_count = await get_all_objs(
+        AccountModel,
+        pageSize,
+        pageIndex,
+        additional_filter=filter_,
+    )
+    return CbhResponseWrapper(
+        data=AllObjectsResponse(
+            paging=Paging(
+                pageSize=pageSize, pageIndex=pageIndex, totalCount=total_count
+            ),
+            data=accounts,
+        )
+    )
+
+
+@account_router.post("/search")
+async def search_accounts(
+    request: SearchRequest,
+    account: AccountModel = Depends(PermissionDependency([AccountType.ADMIN])),
+) -> CbhResponseWrapper[AllObjectsResponse[AccountModel]]:
+    """
+    Search for accounts based on specified criteria.
+    """
+    filter_ = prepare_additional_filter(account)
+    accounts, total = await search_objs(
+        AccountModel,
+        request,
+        additional_filter=filter_,
+    )
+    return CbhResponseWrapper(
+        data=AllObjectsResponse(
+            data=accounts,
+            paging=Paging(
+                totalCount=total, pageSize=request.pageSize, pageIndex=request.pageIndex
+            ),
+        )
+    )
+
+
+@account_router.post(
+    "/filter", description="Used by admin to filter accounts in the teams page"
+)
+async def filter_accounts(
+    request: FilterRequest[AccountFilter],
+    account: AccountModel = Depends(PermissionDependency([AccountType.ADMIN])),
+) -> CbhResponseWrapper[AllObjectsResponse[AccountModel]]:
+    """
+    Filter accounts.
+    """
+    accounts, total_count = await filter_accounts_objs(account, request)
+    return CbhResponseWrapper(
+        data=AllObjectsResponse(
+            data=accounts,
+            paging=Paging(
+                pageSize=request.pageSize,
+                pageIndex=request.pageIndex,
+                totalCount=total_count,
+            ),
+        )
+    )
+
+
+@account_router.get("/{accountId}")
+async def get_account(
+    accountId: str,  # pylint: disable=C0103
+    account: AccountModel = Depends(
+        PermissionDependency([AccountType.ADMIN, AccountType.USER])
+    ),
+) -> CbhResponseWrapper[AccountModel]:
+    """
+    Get an account by ID.
+    """
+    filter_ = prepare_additional_filter(account)
+    account = await get_obj_by_id(AccountModel, accountId, additional_filter=filter_)
+    return CbhResponseWrapper(data=account)
+
+
+@account_router.delete("/{accountId}")
+async def delete_account(
+    accountId: str,
+    account: AccountModel = Depends(PermissionDependency([AccountType.ADMIN])),
+) -> CbhResponseWrapper[AccountModel]:
+    """
+    Delete an account.
+    """
+    await delete_obj(
+        AccountModel,
+        accountId,
+        additional_filter={
+            "organization.id": account.organization.id,
+            "accountType": AccountType.USER.value,
+        },
+    )
+    return CbhResponseWrapper()
+
+
+@account_router.get("")
+async def get_own_account(
+    account: AccountModel = Depends(
+        PermissionDependency([AccountType.ADMIN, AccountType.USER])
+    ),
+) -> CbhResponseWrapper[AccountModel]:
+    """
+    Get own account.
+    """
+    return CbhResponseWrapper(data=account)
+
+
+@account_router.put("")
+async def update_own_account(
+    request: UpdateAccountRequest,
+    account: AccountModel = Depends(
+        PermissionDependency([AccountType.ADMIN, AccountType.USER])
+    ),
+) -> CbhResponseWrapper[AccountModel]:
+    """
+    Update own account.
+    """
+    account = await update_own_account_obj(request, account)
+    return CbhResponseWrapper(data=account)
+
+
+@account_router.post("/picture/upload")
+async def upload_own_account_picture(
+    picture: UploadFile = File(..., description="The picture to upload"),
+    account: AccountModel = Depends(
+        PermissionDependency([AccountType.ADMIN, AccountType.USER])
+    ),
+) -> CbhResponseWrapper[AccountModel]:
+    """
+    Upload own account picture.
+    """
+    picture = compress_image(picture)
+    if account.pictureUrl:
+        settings.S3_CLIENT.update_file(picture, account.pictureUrl, "pictures")
+    else:
+        picture_s3 = settings.S3_CLIENT.upload_file(
+            picture, f"{account.id}.png", "pictures"
+        )
+        account = await update_account_picture_obj(account, picture_s3)
+    return CbhResponseWrapper(data=account)

cbh/api/availability/__init__.py

@@ -0,0 +1,5 @@
+from fastapi import APIRouter
+
+availability_router = APIRouter(prefix="/availability", tags=["availability"])
+
+from . import views

cbh/api/availability/dto.py

@@ -0,0 +1,24 @@
+from enum import Enum
+from datetime import time
+
+from pydantic import BaseModel
+
+
+class DayOfWeek(Enum):
+    MONDAY = 1
+    TUESDAY = 2
+    WEDNESDAY = 3
+    THURSDAY = 4
+    FRIDAY = 5
+    SATURDAY = 6
+    SUNDAY = 7
+
+
+class TimeSlot(BaseModel):
+    startTime: time
+    endTime: time
+
+
+class DaySchedule(BaseModel):
+    dayOfWeek: DayOfWeek
+    slots: list[TimeSlot] | None = None

cbh/api/availability/models.py

@@ -0,0 +1,15 @@
+from cbh.api.availability.dto import DaySchedule
+from cbh.api.timezone.models import TimezoneModel
+from cbh.core.database import MongoBaseModel
+from cbh.api.account.models import AccountShorten
+
+
+class AvailabilityModel(MongoBaseModel):
+    """
+    Availability model.
+    """
+
+    coach: AccountShorten
+    timezone: TimezoneModel
+
+    weeklySchedule: list[DaySchedule] | None = None

cbh/api/availability/schemas.py

@@ -0,0 +1,22 @@
+from pydantic import BaseModel
+from cbh.api.availability.dto import DaySchedule
+from cbh.api.availability.models import AvailabilityModel
+from cbh.api.events.models import EventShorten
+
+
+class UpdateAvailabilityRequest(BaseModel):
+    """
+    Update availability request.
+    """
+
+    timezoneId: str
+    weeklySchedule: list[DaySchedule]
+
+
+class ExtendedAvailabilityResponse(BaseModel):
+    """
+    Extended availability response.
+    """
+
+    availability: AvailabilityModel
+    events: list[EventShorten]

cbh/api/availability/views.py

@@ -0,0 +1,46 @@
+from fastapi import Depends
+from cbh.api.account.models import AccountModel
+from cbh.api.availability.schemas import (
+    UpdateAvailabilityRequest,
+    ExtendedAvailabilityResponse,
+)
+from cbh.core.security import PermissionDependency
+from cbh.api.account.dto import AccountType
+from cbh.core.wrappers import CbhResponseWrapper
+from cbh.api.availability.models import AvailabilityModel
+from cbh.api.availability import availability_router
+
+
+@availability_router.get("")
+async def get_own_availability(
+    account: AccountModel = Depends(PermissionDependency([AccountType.COACH])),
+) -> CbhResponseWrapper[AvailabilityModel]:
+
+    availability = await get_availability_obj(account)
+    return CbhResponseWrapper(data=availability)
+
+
+@availability_router.get("/{coachId}")
+async def get_extended_availability(
+    coachId: str,
+    account: AccountModel = Depends(
+        PermissionDependency([AccountType.ADMIN, AccountType.USER])
+    ),
+) -> CbhResponseWrapper[ExtendedAvailabilityResponse]:
+    """
+    Get availability by coach ID.
+    """
+    availability = await get_extended_availability_obj(coachId)
+    return CbhResponseWrapper(data=availability)
+
+
+@availability_router.put("")
+async def update_own_availability(
+    availability: UpdateAvailabilityRequest,
+    account: AccountModel = Depends(PermissionDependency([AccountType.COACH])),
+) -> CbhResponseWrapper[AvailabilityModel]:
+    """
+    Update own availability.
+    """
+    availability = await update_own_availability_obj(availability, account)
+    return CbhResponseWrapper(data=availability)

cbh/api/calls/__init__.py

@@ -0,0 +1,5 @@
+from fastapi import APIRouter
+
+calls_router = APIRouter(prefix="/calls", tags=["calls"])
+
+from . import views

cbh/api/calls/db_requests.py

@@ -0,0 +1,65 @@
+import asyncio
+
+from cbh.api.account.models import AccountModel, AccountShorten
+from cbh.api.calls.dto import CallStatus
+from cbh.api.calls.models import CallModel
+from cbh.api.calls.schemas import PurchaseCallRequest
+from cbh.api.events.dto import EventType
+from cbh.api.events.models import EventModel, EventShorten
+from cbh.core.config import settings
+
+
+async def create_call_obj(
+    event: EventModel,
+    coach: AccountShorten,
+    customer: AccountModel,
+) -> CallModel:
+    """
+    Create a new call.
+    """
+    call = CallModel(
+        event=EventShorten(**event.model_dump()),
+        customer=AccountShorten(**customer.model_dump()),
+        coach=coach,
+    )
+    await settings.DB_CLIENT.calls.insert_one(call.to_mongo())
+    return call
+
+
+async def create_event_obj(
+    request: PurchaseCallRequest, coach: AccountShorten
+) -> EventModel:
+    """
+    Create a new event.
+    """
+    event = EventModel(
+        type=EventType.CALL,
+        startDate=request.startDate,
+        endDate=request.endDate,
+        coach=coach,
+    )
+    await settings.DB_CLIENT.events.insert_one(event.to_mongo())
+    return event
+
+
+async def disable_call(call: CallModel) -> None:
+    """
+    Disable a call.
+    """
+    call.status = CallStatus.DISABLED
+    call.event.isActive = False
+    await asyncio.gather(
+        settings.DB_CLIENT.calls.update_one({"id": call.id}, {"$set": call.to_mongo()}),
+        settings.DB_CLIENT.events.update_one(
+            {"id": call.event.id}, {"$set": {"isActive": False}}
+        ),
+    )
+
+
+async def enable_call(call: CallModel) -> None:
+    """
+    Enable a call.
+    """
+    await settings.DB_CLIENT.calls.update_one(
+        {"id": call.id}, {"$set": {"status": CallStatus.SCHEDULED}}
+    )

cbh/api/calls/dto.py

@@ -0,0 +1,14 @@
+from enum import Enum
+
+
+class CallStatus(Enum):
+    """
+    Call status.
+    """
+
+    CREATED = 0
+    DISABLED = 1
+    SCHEDULED = 2
+    COMPLETED = 3
+    CANCELLED_BY_CUSTOMER = 4
+    CANCELLED_BY_COACH = 5

cbh/api/calls/models.py

@@ -0,0 +1,25 @@
+from datetime import datetime
+
+from pydantic import Field
+
+from cbh.api.account.models import AccountShorten
+from cbh.api.calls.dto import CallStatus
+from cbh.api.events.models import EventShorten
+from cbh.core.database import MongoBaseModel
+
+
+class CallModel(MongoBaseModel):
+    """
+    Call model.
+    """
+
+    event: EventShorten
+
+    customer: AccountShorten
+    coach: AccountShorten
+
+    duration: int | None = None
+
+    status: CallStatus = CallStatus.CREATED
+
+    datetimeInserted: datetime = Field(default_factory=datetime.now)

cbh/api/calls/schemas.py

@@ -0,0 +1,21 @@
+from datetime import datetime
+
+from pydantic import BaseModel
+
+
+class StripeSessionResponse(BaseModel):
+    """
+    Stripe session response.
+    """
+
+    sessionUrl: str
+
+
+class PurchaseCallRequest(BaseModel):
+    """
+    Purchase call request.
+    """
+
+    coachId: str
+    startDate: datetime
+    endDate: datetime

cbh/api/calls/services/__init__.py

@@ -0,0 +1,3 @@
+from .stripe import create_stripe_session, verify_stripe_webhook, manage_stripe_event
+
+__all__ = ["create_stripe_session", "verify_stripe_webhook", "manage_stripe_event"]

cbh/api/calls/services/stripe.py

@@ -0,0 +1,73 @@
+import time
+
+import pydash
+import stripe
+from fastapi import HTTPException, Request
+
+from cbh.api.calls.db_requests import disable_call, enable_call
+from cbh.api.calls.models import CallModel
+from cbh.api.common.db_requests import get_obj_by_id
+from cbh.core.config import settings
+
+
+async def create_stripe_session(call: CallModel) -> str:
+    """
+    Create a stripe session.
+    """
+    metadata = {
+        "callId": call.id,
+    }
+
+    checkout_session = await settings.STRIPE_CLIENT.checkout.sessions.create_async(
+        payment_method_types=["card", "ideal"],
+        line_items=[
+            {
+                "price_data": {
+                    "currency": "usd",
+                    "unit_amount": 15,
+                    "product_data": {
+                        "name": f"Call ({call.duration} minutes)",
+                        "description": f"Payment for a call of {call.duration} minutes",
+                    },
+                },
+                "quantity": 1,
+            },
+        ],
+        mode="payment",
+        success_url=f"{settings.Audience}",
+        cancel_url=f"{settings.Audience}",
+        metadata=metadata,
+        expires_at=int(time.time()) + 1800,
+    )
+    return checkout_session.url
+
+
+async def verify_stripe_webhook(request: Request, payload: bytes) -> dict:
+    """
+    Verify a stripe webhook.
+    """
+    sig_header = request.headers.get("stripe-signature")
+
+    try:
+        event = stripe.Webhook.construct_event(
+            payload, sig_header, settings.STRIPE_WEBHOOK_SECRET
+        )
+        return event
+    except stripe.error.SignatureVerificationError as e:
+        raise HTTPException(status_code=400, detail="Invalid request")
+
+
+async def manage_stripe_event(event: dict) -> str:
+    """
+    Manage a stripe event.
+    """
+    event_type = event["type"]
+    call_id = pydash.get(event, "data.object.metadata.callId")
+    call = await get_obj_by_id(CallModel, call_id)
+
+    if event_type != "checkout.session.completed":
+        await disable_call(call)
+        return f"{settings.Audience}/stripe/error?event_type={event_type}"
+
+    await enable_call(call)
+    return f"{settings.Audience}/stripe/success"

cbh/api/calls/views.py

@@ -0,0 +1,44 @@
+from fastapi import Depends, Request
+from fastapi.responses import RedirectResponse
+
+from cbh.api.account.dto import AccountType
+from cbh.api.account.models import AccountModel, AccountShorten
+from cbh.api.calls import calls_router
+from cbh.api.calls.db_requests import create_call_obj, create_event_obj
+from cbh.api.calls.schemas import PurchaseCallRequest, StripeSessionResponse
+from cbh.api.calls.services import (
+    create_stripe_session,
+    manage_stripe_event,
+    verify_stripe_webhook,
+)
+from cbh.api.common.db_requests import get_obj_by_id
+from cbh.core.security import PermissionDependency
+from cbh.core.wrappers import CbhResponseWrapper
+
+
+@calls_router.post("/stripe/purchase")
+async def purchase_call(
+    request: PurchaseCallRequest,
+    account: AccountModel = Depends(PermissionDependency([AccountType.USER])),
+) -> CbhResponseWrapper[StripeSessionResponse]:
+    """
+    Purchase a call.
+    """
+    coach = await get_obj_by_id(
+        AccountShorten, request.coachId, projection=AccountShorten.to_mongo_fields()
+    )
+    event = await create_event_obj(request, coach)
+    call = await create_call_obj(event, coach, account)
+    session_url = await create_stripe_session(call)
+    return CbhResponseWrapper(data=StripeSessionResponse(sessionUrl=session_url))
+
+
+@calls_router.post("/stripe/callback")
+async def stripe_callback(request: Request) -> RedirectResponse:
+    """
+    Stripe callback.
+    """
+    payload = await request.body()
+    event = await verify_stripe_webhook(request, payload)
+    redirect_url = await manage_stripe_event(event)
+    return RedirectResponse(redirect_url)

cbh/api/common/db_requests.py

@@ -0,0 +1,230 @@
+"""
+Common database requests.
+"""
+
+import asyncio
+import re
+from datetime import timedelta, datetime
+from typing import TypeVar
+
+from fastapi import HTTPException
+from pydantic import BaseModel
+
+from cbh.api.common.schemas import (
+    SearchRequest,
+)
+from cbh.core.config import settings
+
+T = TypeVar("T", bound=BaseModel)
+
+collection_map = {
+    "AccountModel": "accounts",
+    "AccountShorten": "accounts",
+    "ScenarioModel": "scenarios",
+    "ScenarioShorten": "scenarios",
+    "SessionReportModel": "sessionreports",
+    "SessionReportShorten": "sessionreports",
+    "TeamModel": "teams",
+    "TeamModelShorten": "teams",
+    "OrganizationModel": "organizations",
+    "OrganizationShorten": "organizations",
+    "OrganizationDocumentModel": "organizationdocuments",
+    "OrganizationSettingsModel": "organizationsettings",
+    "UserInsightModel": "userinsights",
+    "UserInsightShorten": "userinsights",
+    "VoiceModel": "voices",
+    "VoiceModelShorten": "voices",
+    "ActivityLogModel": "activitylogs",
+    "AccountNotificationModel": "accountnotifications",
+    "FeedbackModel": "generalfeedbacks",
+    "FeedbackExtendedModel": "extendedfeedbacks",
+    "ScenarioChangeModel": "scenariochanges",
+    "WaitlistModel": "waitlists",
+    "NotificationModel": "notifications",
+    "NotificationModelShorten": "notifications",
+}
+
+
+async def get_obj_by_id(
+    model: T,
+    obj_id: str | None,
+    additional_filter: dict | None = None,
+    projection: dict | None = None,
+    exception: bool = True,
+) -> T | None:
+    """
+    Get an object by ID.
+    """
+    filter_ = {"id": obj_id} if obj_id else {}
+    if additional_filter:
+        filter_.update(additional_filter)
+    obj = await settings.DB_CLIENT[collection_map[model.__name__]].find_one(
+        filter_, projection
+    )
+    if obj is None:
+        if exception:
+            raise HTTPException(status_code=404, detail="Object not found.")
+        else:
+            return None
+    return model.from_mongo(obj)
+
+
+async def get_all_objs(
+    model: T,
+    page_size: int,
+    page_index: int,
+    sort: tuple[str, int] = ("id", -1),
+    additional_filter: dict | None = None,
+    projection: dict | None = None,
+) -> tuple[list[T], int]:
+    """
+    Get all objects.
+    """
+    filter_ = additional_filter if additional_filter else {}
+    skip = page_index * page_size
+    objs, total_count = await asyncio.gather(
+        settings.DB_CLIENT[collection_map[model.__name__]]
+        .find(filter_, projection)
+        .sort(*sort)
+        .skip(skip)
+        .limit(page_size)
+        .to_list(page_size),
+        settings.DB_CLIENT[collection_map[model.__name__]].count_documents(filter_),
+    )
+    return [model.from_mongo(obj) for obj in objs], total_count
+
+
+async def delete_obj(
+    model: T, obj_id: str | None = None, additional_filter: dict | None = None
+) -> T:
+    """
+    Delete an object.
+    """
+    filter_ = {"id": obj_id} if obj_id else {}
+    if additional_filter:
+        filter_.update(additional_filter)
+    obj = await settings.DB_CLIENT[collection_map[model.__name__]].find_one(filter_)
+    if obj is None:
+        raise HTTPException(status_code=404, detail="Object not found.")
+    await settings.DB_CLIENT[collection_map[model.__name__]].delete_one(filter_)
+    return model.from_mongo(obj)
+
+
+async def search_objs(
+    model: T,
+    data: SearchRequest,
+    additional_filter: dict | None = None,
+    projection: dict | None = None,
+) -> tuple[list[T], int]:
+    """
+    Search for objects in a specified collection based on search filters.
+    """
+    filters = []
+    date_filters = {}
+
+    for search_filter in data.filter:
+        if isinstance(search_filter.value, str):
+            date_match = re.fullmatch(
+                r"^(\d{4}-\d{2}-\d{2});([+-]\d{1,2})$", search_filter.value
+            )
+
+            if date_match:
+                if search_filter.name not in date_filters:
+                    date_filters[search_filter.name] = []
+
+                date_filters[search_filter.name].append(
+                    {
+                        "date": datetime.strptime(date_match.group(1), "%Y-%m-%d"),
+                        "timezone_offset": int(date_match.group(2)),
+                    }
+                )
+            else:
+                filters.append(
+                    {
+                        search_filter.name: {
+                            "$regex": f"^{re.escape(search_filter.value)}",
+                            "$options": "i",
+                        }
+                    }
+                )
+        else:
+            filters.append({search_filter.name: search_filter.value})
+
+    for field_name, dates in date_filters.items():
+        if len(dates) == 1:
+            date_info = dates[0]
+            user_local_day_start = date_info["date"]
+            user_local_day_end = user_local_day_start + timedelta(days=1)
+            filters.append(
+                {
+                    field_name: {
+                        "$gte": (
+                            user_local_day_start
+                            - timedelta(hours=date_info["timezone_offset"])
+                        ).isoformat(),
+                        "$lt": (
+                            user_local_day_end
+                            - timedelta(hours=date_info["timezone_offset"])
+                        ).isoformat(),
+                    }
+                }
+            )
+        elif len(dates) == 2:
+            start_date = min(dates, key=lambda x: x["date"])
+            end_date = max(dates, key=lambda x: x["date"])
+
+            start_datetime = start_date["date"] - timedelta(
+                hours=start_date["timezone_offset"]
+            )
+            end_datetime = (
+                end_date["date"]
+                + timedelta(days=1)
+                - timedelta(hours=end_date["timezone_offset"])
+            )
+
+            filters.append(
+                {
+                    field_name: {
+                        "$gte": start_datetime.isoformat(),
+                        "$lt": end_datetime.isoformat(),
+                    }
+                }
+            )
+        elif len(dates) > 2:
+            dates_sorted = sorted(dates, key=lambda x: x["date"])
+            start_date = dates_sorted[0]
+            end_date = dates_sorted[-1]
+
+            start_datetime = start_date["date"] - timedelta(
+                hours=start_date["timezone_offset"]
+            )
+            end_datetime = (
+                end_date["date"]
+                + timedelta(days=1)
+                - timedelta(hours=end_date["timezone_offset"])
+            )
+
+            filters.append(
+                {
+                    field_name: {
+                        "$gte": start_datetime.isoformat(),
+                        "$lt": end_datetime.isoformat(),
+                    }
+                }
+            )
+
+    if additional_filter:
+        filters.append(additional_filter)
+    regex_filter = {"$and": filters} if filters else {}
+    objects, total_count = await asyncio.gather(
+        settings.DB_CLIENT[collection_map[model.__name__]]
+        .find(regex_filter, projection)
+        .sort("id", -1)
+        .skip(data.pageSize * data.pageIndex)
+        .limit(data.pageSize)
+        .to_list(length=data.pageSize),
+        settings.DB_CLIENT[collection_map[model.__name__]].count_documents(
+            regex_filter
+        ),
+    )
+    return [model.from_mongo(obj) for obj in objects], total_count

cbh/api/common/dto.py

@@ -0,0 +1,146 @@
+"""
+Common DTOs.
+"""
+
+from datetime import datetime
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+from cbh.api.account.models import AccountShorten
+
+
+class Paging(BaseModel):
+    """
+    Pagination model for API responses.
+    """
+
+    pageSize: int
+    pageIndex: int
+    totalCount: int
+
+
+class SearchFilter(BaseModel):
+    """
+    Search filter model for constructing database queries.
+
+    Attributes:
+        name (str): Field name to filter on
+        value (str | int): Value to search for
+    """
+
+    name: str
+    value: str | int
+
+
+class Scores(BaseModel):
+    """
+    Scores for the recording.
+    """
+
+    communication: int = Field(
+        description="Speech professionalism assessment: clarity of presentation, absence of filler words, literacy, 1-100",
+    )
+
+    activeListening: int = Field(
+        description="Active listening skills: ability to ask clarifying questions, respond to client signals, 1-100",
+    )
+
+    conversation: int = Field(
+        description="Conversation control: ability to direct conversation, adhere to sales structure, 1-100",
+    )
+
+    objection: int = Field(
+        description="Objection handling: ability to correctly respond to client doubts and overcome obstacles, 1-100",
+    )
+
+    empathy: int = Field(
+        description="Emotional intelligence: adaptation to client mood, empathy, building rapport, 1-100",
+    )
+
+    final: int = Field(
+        description="Overall score: score of completion of conversation, 1-100",
+    )
+
+    def __sub__(self, other: "Scores") -> "Scores":
+        return Scores(
+            communication=self.communication - other.communication,
+            activeListening=self.activeListening - other.activeListening,
+            conversation=self.conversation - other.conversation,
+            objection=self.objection - other.objection,
+            empathy=self.empathy - other.empathy,
+            final=self.final - other.final,
+        )
+
+    def __mod__(self, other: "Scores") -> "Scores":
+        def calc_percentage_diff(current: int, previous: int) -> int:
+            if previous == 0:
+                return 0
+            return int(((current - previous) / previous) * 100)
+
+        return Scores(
+            communication=calc_percentage_diff(self.communication, other.communication),
+            activeListening=calc_percentage_diff(
+                self.activeListening, other.activeListening
+            ),
+            conversation=calc_percentage_diff(self.conversation, other.conversation),
+            objection=calc_percentage_diff(self.objection, other.objection),
+            empathy=calc_percentage_diff(self.empathy, other.empathy),
+            final=calc_percentage_diff(self.final, other.final),
+        )
+
+
+class DateValue(BaseModel):
+    """
+    Date value.
+    """
+
+    date: datetime
+    value: int
+
+
+class ValueDelta(BaseModel):
+    """
+    Value delta.
+    """
+
+    value: int
+    delta: int
+
+
+class IDName(BaseModel):
+    id: str | int
+    name: str
+
+
+class OrderType(Enum):
+    """
+    Order type.
+    """
+
+    ASCENDING = 1
+    DESCENDING = -1
+
+
+class SortBy(BaseModel):
+    """
+    Sort by.
+    """
+
+    name: str
+    order: OrderType
+
+
+class TokenUsage(BaseModel):
+    inputTokens: int
+    outputTokens: int
+
+
+class LeaderboardPosition(BaseModel):
+    """
+    Leaderboard position model.
+    """
+
+    user: AccountShorten
+    finalScore: int
+    attempts: int

cbh/api/common/schemas.py

@@ -0,0 +1,70 @@
+"""
+Common schemas.
+"""
+
+from typing import TypeVar, Generic
+
+from pydantic import BaseModel
+
+from cbh.api.common.dto import Paging, SearchFilter, SortBy
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class AllObjectsResponse(BaseModel, Generic[T]):
+    """
+    Response model for all objects.
+    """
+
+    paging: Paging
+    data: list[T]
+
+
+class SearchRequest(BaseModel):
+    """
+    Request schema for searching calls or statistics.
+
+    Attributes:
+        filter (list[SearchFilter]): List of filters to apply
+        pageSize (int): Number of items to return per page
+        pageIndex (int): Page index to retrieve
+    """
+
+    filter: list[SearchFilter]
+    pageSize: int
+    pageIndex: int
+
+
+class FilterRequest(BaseModel, Generic[T]):
+    """
+    Filter request.
+    """
+
+    filter: T
+    sortBy: SortBy | None = None
+    pageSize: int = 10
+    pageIndex: int = 0
+
+
+class PlainTextResponse(BaseModel):
+    """
+    Response model for plain text.
+    """
+
+    text: str
+
+
+class BatchIdsRequest(BaseModel):
+    """
+    Batch ids request.
+    """
+
+    ids: list[str]
+
+
+class EmailRequest(BaseModel):
+    """
+    Email request.
+    """
+
+    email: str

cbh/api/common/utils.py

@@ -0,0 +1,84 @@
+"""
+Common utilities.
+"""
+
+import asyncio
+import base64
+import re
+
+import httpx
+
+from cbh.api.account.dto import AccountType
+from cbh.api.account.models import AccountModel
+from cbh.api.scenario.dto import AssigneesType
+from cbh.core.config import settings
+
+
+def form_additional_scenario_filter(account: AccountModel):
+    filter_ = {"owner.organization.id": account.organization.id}
+    if account.accountType == AccountType.USER:
+        filter_.update(
+            {
+                "$or": [
+                    {"assignees": {"$size": 0}},
+                    {
+                        "assignees": {
+                            "$elemMatch": {
+                                "type": AssigneesType.USER.value,
+                                "account.id": account.id,
+                            }
+                        }
+                    },
+                    {
+                        "assignees": {
+                            "$elemMatch": {
+                                "type": AssigneesType.TEAM.value,
+                                "team.members": {"$elemMatch": {"id": account.id}},
+                            }
+                        }
+                    },
+                ],
+            }
+        )
+    return filter_
+
+
+async def convert_document_to_text(file: bytes, filename: str) -> str:
+    filename = re.sub(r"[^\w\s.-]", "", filename)
+    base64_file = base64.b64encode(file).decode("utf-8")
+    headers = {"Content-Type": "application/json"}
+    data = {
+        "apikey": settings.CONVERTIO_API_KEY,
+        "input": "base64",
+        "file": base64_file,
+        "filename": filename,
+        "outputformat": "txt",
+    }
+    async with httpx.AsyncClient(timeout=httpx.Timeout(timeout=120)) as client:
+        response = await client.post(
+            "https://api.convertio.co/convert", json=data, headers=headers
+        )
+        response = response.json()
+        if response["code"] == 200:
+            conversion_id = response["data"]["id"]
+            status = ""
+            attempt = 0
+            while status != "finish":
+                if attempt > 50:
+                    raise Exception("Please, try again")
+                get_status_response = await client.get(
+                    f"https://api.convertio.co/convert/{conversion_id}/status"
+                )
+                get_status_response = get_status_response.json()
+                if get_status_response["code"] != 200:
+                    raise Exception("Please, try again")
+                else:
+                    status = get_status_response["data"]["step"]
+                    await asyncio.sleep(1)
+                attempt += 1
+            file_url = get_status_response["data"]["output"]["url"]
+            response = await client.get(file_url)
+            response.raise_for_status()
+            return response.content.decode("utf-8", errors="ignore")
+        else:
+            return ""

cbh/api/events/__init__.py

@@ -0,0 +1,5 @@
+from fastapi import APIRouter
+
+events_router = APIRouter(prefix="/events", tags=["events"])
+
+from . import views

cbh/api/events/db_requests.py

@@ -0,0 +1,21 @@
+from cbh.api.account.models import AccountModel, AccountShorten
+from cbh.api.events.models import EventModel
+from cbh.api.events.schemas import CreateEventRequest
+from cbh.core.config import settings
+
+
+async def create_event_obj(
+    event: CreateEventRequest, account: AccountModel
+) -> EventModel:
+    """
+    Create a new event.
+    """
+    event = EventModel(
+        reason=event.reason,
+        type=event.type,
+        startDate=event.startDate,
+        endDate=event.endDate,
+        coach=AccountShorten(**account.model_dump()),
+    )
+    await settings.DB_CLIENT.events.insert_one(event.to_mongo())
+    return event

cbh/api/events/dto.py

@@ -0,0 +1,10 @@
+from enum import Enum
+
+
+class EventType(Enum):
+    """
+    Event type.
+    """
+
+    CALL = 1
+    CUSTOM = 2

cbh/api/events/models.py

@@ -0,0 +1,33 @@
+from datetime import datetime
+from pydantic import Field
+from cbh.api.events.dto import EventType
+from cbh.core.database import MongoBaseModel, MongoBaseShortenModel
+from cbh.api.account.models import AccountShorten
+
+
+class EventModel(MongoBaseModel):
+    """
+    Event model.
+    """
+
+    reason: str | None = None
+    type: EventType
+
+    startDate: datetime
+    endDate: datetime
+
+    coach: AccountShorten
+
+    isActive: bool = True
+    datetimeInserted: datetime = Field(default_factory=datetime.now)
+
+
+class EventShorten(MongoBaseShortenModel):
+    """
+    Event shorten model.
+    """
+
+    startDate: datetime
+    endDate: datetime
+
+    isActive: bool

cbh/api/events/schemas.py

@@ -0,0 +1,15 @@
+from datetime import datetime
+from pydantic import BaseModel
+from cbh.api.events.dto import EventType
+
+
+class CreateEventRequest(BaseModel):
+    """
+    Create event request.
+    """
+
+    reason: str | None = None
+    type: EventType
+
+    startDate: datetime
+    endDate: datetime

cbh/api/events/views.py

@@ -0,0 +1,22 @@
+from fastapi import Depends
+
+from cbh.api.events import events_router
+from cbh.api.events.models import EventModel
+from cbh.api.account.models import AccountModel
+from cbh.core.security import PermissionDependency
+from cbh.api.account.dto import AccountType
+from cbh.core.wrappers import CbhResponseWrapper
+from cbh.api.events.schemas import CreateEventRequest
+from cbh.api.events.db_requests import create_event_obj
+
+
+@events_router.post("/")
+async def create_event(
+    event: CreateEventRequest,
+    account: AccountModel = Depends(PermissionDependency([AccountType.COACH])),
+) -> CbhResponseWrapper[EventModel]:
+    """
+    Create a new event.
+    """
+    event = await create_event_obj(event, account)
+    return CbhResponseWrapper(data=event)

cbh/api/security/__init__.py

@@ -0,0 +1,11 @@
+"""
+Security module initialization.
+"""
+
+from fastapi import APIRouter
+
+security_router = APIRouter(
+    prefix="/api/security",
+)
+
+from . import views  # pylint: disable=C0413  # noqa: E402,F401

cbh/api/security/db_requests.py

@@ -0,0 +1,105 @@
+"""
+Database requests module for security functionality.
+"""
+
+from datetime import datetime
+
+from fastapi import HTTPException
+from passlib.context import CryptContext
+from pydantic import EmailStr
+
+from cbh.api.account.dto import AccountStatus
+from cbh.api.account.models import AccountModel, AccountShorten
+from cbh.api.security.schemas import (
+    LoginAccountRequest,
+    RegisterAccountRequest,
+)
+from cbh.core.config import settings
+from cbh.core.security import verify_password
+
+
+async def check_unique_fields_existence(
+    name: str, new_value: EmailStr | str, current_value: str | None = None
+) -> None:
+    """
+    Check if a field value already exists in the database to ensure uniqueness.
+    """
+    if new_value == current_value or not new_value:
+        return
+    account = await settings.DB_CLIENT.accounts.find_one(
+        {name: {"$regex": f"^{str(new_value)}$", "$options": "i"}}
+    )
+    if account:
+        detail = f'Account with {name} "{new_value}" already exists.'
+        raise HTTPException(status_code=400, detail=detail)
+
+
+async def save_account(data: RegisterAccountRequest) -> AccountModel:
+    """
+    Create a new user account in the database.
+    """
+    await check_unique_fields_existence("email", data.email)
+    account = AccountModel(
+        name=f"{data.firstName} {data.lastName}",
+        email=data.email,
+        password=data.password,
+        status=AccountStatus.ACTIVE,
+        datetimeUpdated=datetime.now(),
+    )
+    await settings.DB_CLIENT.accounts.insert_one(account.to_mongo())
+    return account
+
+
+async def authenticate_account(data: LoginAccountRequest) -> AccountModel:
+    """
+    Authenticate a user account using mail and password.
+    """
+    account = await settings.DB_CLIENT.accounts.find_one(
+        {"email": {"$regex": f"^{data.email}$", "$options": "i"}}
+    )
+    if account is None:
+        raise HTTPException(status_code=404, detail="Invalid email or password.")
+
+    account = AccountModel.from_mongo(account)
+
+    if not verify_password(data.password, account.password):
+        raise HTTPException(status_code=401, detail="Invalid email or password")
+
+    if account.status == AccountStatus.PENDING_INVITATION:
+        raise HTTPException(
+            status_code=403,
+            detail="Account not activated. Please accept your invitation",
+        )
+
+    if account.status == AccountStatus.BLOCKED:
+        raise HTTPException(status_code=423, detail="Account is blocked")
+
+    return account
+
+
+async def get_account_by_email(
+    email: EmailStr, raise_exception: bool = True
+) -> AccountModel | None:
+    """
+    Verify if an account exists.
+    """
+    account = await settings.DB_CLIENT.accounts.find_one(
+        {"email": {"$regex": f"^{email}$", "$options": "i"}}
+    )
+    if account is None and raise_exception:
+        raise HTTPException(status_code=404, detail="Account not found")
+    elif account is None:
+        return None
+    return AccountModel.from_mongo(account)
+
+
+async def reset_password_obj(account: AccountShorten, password: str) -> AccountModel:
+    """
+    Reset a password object.
+    """
+    password = CryptContext(schemes=["bcrypt"], deprecated="auto").hash(password)
+    await settings.DB_CLIENT.accounts.update_one(
+        {"id": account.id},
+        {"$set": {"password": password}},
+    )
+    return account

cbh/api/security/dto.py

@@ -0,0 +1,14 @@
+"""
+Data Transfer Objects (DTOs) for security functionality.
+"""
+
+from pydantic import BaseModel
+
+
+class AccessToken(BaseModel):
+    """
+    Access token model for authentication.
+    """
+
+    type: str = "Bearer"
+    value: str

cbh/api/security/schemas.py

@@ -0,0 +1,37 @@
+"""
+Schema definitions for security API endpoints.
+"""
+
+from pydantic import BaseModel, EmailStr
+
+from cbh.api.account.models import AccountModel
+from cbh.api.security.dto import AccessToken
+
+
+class RegisterAccountRequest(BaseModel):
+    """
+    Request model for account registration.
+    """
+
+    firstName: str
+    lastName: str
+    email: str
+    password: str
+
+
+class LoginAccountRequest(BaseModel):
+    """
+    Request model for account login.
+    """
+
+    email: EmailStr
+    password: str
+
+
+class LoginAccountResponse(BaseModel):
+    """
+    Response model for successful login.
+    """
+
+    accessToken: AccessToken | None = None
+    account: AccountModel

cbh/api/security/utils.py

@@ -0,0 +1,122 @@
+"""
+Security utilities module.
+"""
+
+import asyncio
+
+from fastapi import HTTPException
+from jinja2 import Environment, FileSystemLoader, select_autoescape
+
+from cbh.api.account.dto import RegistrationType
+from cbh.api.account.models import AccountModel, AccountShorten
+from cbh.api.security.models import VerificationCodeModel
+from cbh.core.config import settings
+
+
+def check_account_to_reset(
+    account_obj: AccountModel, account: AccountModel | None = None
+) -> None:
+    """
+    Check if the account can be reset.
+    """
+    if not account and account_obj.registrationType != RegistrationType.ORGANIC:
+        raise HTTPException(
+            status_code=422,
+            detail="Please sign in with social providers",
+        )
+    elif account and account_obj.registrationType != RegistrationType.ORGANIC:
+        raise HTTPException(
+            status_code=422,
+            detail="Password reset is not available for social login accounts",
+        )
+
+
+async def send_password_reset_email(
+    code: str, account_obj: AccountModel, account: AccountModel | None = None
+) -> None:
+    """
+    Send a password reset email.
+    """
+    templates_path = settings.BASE_DIR / "cbh" / "templates" / "emails"
+    env = Environment(
+        loader=FileSystemLoader(templates_path),
+        autoescape=select_autoescape(["html", "xml"]),
+    )
+    template = env.get_template("resetPassword.html")
+
+    audience_link = settings.Domain
+    if account_obj.organization:
+        audience_link = f"{account_obj.organization.slug}.{settings.Domain}"
+
+    link = f"{settings.Audience}/reset?code={code}"
+    if account:
+        link = f"https://{account.organization.slug}.{settings.Domain}/settings/change-password?code={code}"
+
+    template_content = template.render(
+        link=link,
+        audience_link=audience_link,
+    )
+    await settings.EMAIL_CLIENT.send_email(
+        account_obj.email,
+        "You requested a password reset in Arena",
+        template_content,
+    )
+
+
+def _prepare_joins_str(org_accounts: list[AccountShorten]):
+    if not org_accounts:
+        return None
+    if len(org_accounts) == 1:
+        return f"{org_accounts[0].name} has joined"
+    elif len(org_accounts) == 2:
+        return f"{org_accounts[0].name} and {org_accounts[1].name} have joined"
+    return f"{org_accounts[0].name} and {len(org_accounts) - 1} others have joined"
+
+
+async def send_invite_email(
+    admin_account: AccountModel,
+    code: VerificationCodeModel,
+    org_accounts: list[AccountShorten],
+    email: str,
+    message: str | None = None,
+) -> None:
+    """
+    Send an invite email.
+    """
+    templates_path = settings.BASE_DIR / "cbh" / "templates" / "emails"
+    env = Environment(
+        loader=FileSystemLoader(templates_path),
+        autoescape=select_autoescape(["html", "xml"]),
+    )
+    template = env.get_template("inviteToOrg.html")
+
+    icons = [
+        org_account.pictureUrl for org_account in org_accounts if org_account.pictureUrl
+    ][:3]
+    joins_str = _prepare_joins_str(org_accounts)
+
+    template_content = template.render(
+        admin_name=admin_account.name,
+        organization_name=admin_account.organization.name,
+        link=f"{settings.Audience}/signup?code={code.id}",
+        icons=icons if icons else None,
+        joins_str=joins_str,
+        audience_link=f"{admin_account.organization.slug}.{settings.Domain}",
+        message=message,
+    )
+
+    await settings.EMAIL_CLIENT.send_email(
+        email,
+        f"{admin_account.name.title()} invited you to train with them in Arena",
+        template_content,
+    )
+
+
+async def delete_account():
+    await settings.DB_CLIENT.accounts.delete_one(
+        {"email": "maksimshymanouski@gmail.com"}
+    )
+
+
+if __name__ == "__main__":
+    asyncio.run(delete_account())

cbh/api/security/views.py

@@ -0,0 +1,80 @@
+"""
+Security API views module.
+"""
+
+from fastapi import Depends, HTTPException
+
+from cbh.api.account.dto import AccountType
+from cbh.api.account.models import AccountModel
+from cbh.api.common.db_requests import get_obj_by_id
+from cbh.api.security import security_router
+from cbh.api.security.db_requests import (
+    save_account,
+    authenticate_account,
+)
+from cbh.api.security.dto import AccessToken
+from cbh.api.security.schemas import (
+    RegisterAccountRequest,
+    LoginAccountRequest,
+    LoginAccountResponse,
+)
+from cbh.core.security import PermissionDependency, create_access_token
+from cbh.core.wrappers import CbhResponseWrapper
+
+
+@security_router.post("/register")
+async def register_user(
+    data: RegisterAccountRequest,
+) -> CbhResponseWrapper[AccountModel]:
+    """
+    Register a new user account.
+    """
+    account = await save_account(data)
+    return CbhResponseWrapper(data=account)
+
+
+@security_router.post("/login")
+async def login(data: LoginAccountRequest) -> CbhResponseWrapper[LoginAccountResponse]:
+    """
+    Authenticate a user and generate an access token.
+    """
+    account = await authenticate_account(data)
+    access_token = create_access_token(
+        account.email, str(account.id), account.accountType
+    )
+    response = LoginAccountResponse(
+        accessToken=AccessToken(value=access_token),
+        account=account,
+    )
+    return CbhResponseWrapper(data=response)
+
+
+@security_router.post("/verify")
+async def verify(
+    account: AccountModel = Depends(
+        PermissionDependency([AccountType.ADMIN, AccountType.USER])
+    ),
+) -> CbhResponseWrapper[AccountModel]:
+    """
+    Verify a user's authentication token.
+    """
+    return CbhResponseWrapper(data=account)
+
+
+@security_router.post("/login/as/user")
+async def login_as_user(
+    accountId: str,
+    # _: AccountModel = Depends(PermissionDependency([AccountType.ADMIN])),
+) -> CbhResponseWrapper[LoginAccountResponse]:
+    """
+    Login as a user.
+    """
+    account = await get_obj_by_id(AccountModel, accountId)
+    if account is None:
+        raise HTTPException(status_code=404, detail="User not found")
+    token = create_access_token(account.email, str(account.id), account.accountType)
+    response = LoginAccountResponse(
+        accessToken=AccessToken(value=token),
+        account=account,
+    )
+    return CbhResponseWrapper(data=response)

cbh/api/timezone/__init__.py

@@ -0,0 +1,7 @@
+from fastapi import APIRouter
+
+timezone_router = APIRouter(
+    prefix="/api/timezone",
+)
+
+from . import views

cbh/api/timezone/models.py

@@ -0,0 +1,10 @@
+from cbh.core.database import MongoBaseModel
+
+
+class TimezoneModel(MongoBaseModel):
+    """
+    Timezone model.
+    """
+
+    name: str
+    offset: str

cbh/api/timezone/views.py

@@ -0,0 +1,26 @@
+from fastapi import Depends
+
+from cbh.api.account.models import AccountModel
+from cbh.api.common.db_requests import search_objs
+from cbh.api.common.dto import Paging
+from cbh.api.common.schemas import AllObjectsResponse, SearchRequest
+from cbh.api.timezone import timezone_router
+from cbh.api.timezone.models import TimezoneModel
+from cbh.core.security import PermissionDependency
+from cbh.core.wrappers import CbhResponseWrapper
+
+
+@timezone_router.post("/search")
+async def search_industries(
+    request: SearchRequest,
+    _: AccountModel = Depends(PermissionDependency()),
+) -> CbhResponseWrapper[AllObjectsResponse[TimezoneModel]]:
+    industries, total = await search_objs(TimezoneModel, request)
+    return CbhResponseWrapper(
+        data=AllObjectsResponse(
+            data=industries,
+            paging=Paging(
+                pageSize=request.pageSize, pageIndex=request.pageIndex, totalCount=total
+            ),
+        )
+    )

cbh/core/config.py

@@ -0,0 +1,110 @@
+"""
+Configuration module for ClipboardHealthAI application.
+"""
+
+import os
+import pathlib
+from functools import lru_cache
+from typing import Optional, Type
+
+from dotenv import load_dotenv
+from langchain_core.runnables import Runnable
+from langchain_openai import ChatOpenAI, OpenAIEmbeddings
+from motor.motor_asyncio import AsyncIOMotorClient, AsyncIOMotorDatabase
+from pydantic import BaseModel
+from stripe import StripeClient
+
+load_dotenv()
+
+
+class BaseConfig:
+    """
+    Base configuration class containing common settings for all environments.
+    """
+
+    BASE_DIR: pathlib.Path = pathlib.Path(__file__).parent.parent.parent
+    SECRET_KEY: str = os.getenv("SECRET", "")
+
+    DB_CLIENT: AsyncIOMotorDatabase = AsyncIOMotorClient(
+        os.getenv("MONGO_DB_URL")
+    ).spark
+
+    STRIPE_CLIENT = StripeClient(api_key=os.getenv("STRIPE_API_KEY"))
+    STRIPE_WEBHOOK_SECRET = os.getenv("STRIPE_WEBHOOK_SECRET")
+
+    @staticmethod
+    def get_headers(api_key: str) -> dict:
+        """
+        Generate HTTP headers for API requests.
+        """
+        return {
+            "Authorization": f"Bearer {api_key}",
+            "Content-Type": "application/json",
+            "Accept": "application/json",
+        }
+
+    @staticmethod
+    @lru_cache()
+    def get_llm(
+        model: str = "gpt-4.1-mini",
+        temperature: float = 0.0,
+        reasoning: str = "none",
+        schema: Optional[Type[BaseModel]] = None,
+        is_json: bool = False,
+    ) -> Runnable:
+        """
+        Get a configured LLM instance.
+        """
+        kwargs = {"model": model, "temperature": temperature}
+        if model.startswith("gpt-5"):
+            kwargs["reasoning_effort"] = reasoning
+            kwargs["temperature"] = 1
+        if schema:
+            return ChatOpenAI(**kwargs).with_structured_output(schema)
+        if is_json:
+            return ChatOpenAI(**kwargs).with_structured_output(method="json_mode")
+        return ChatOpenAI(**kwargs)
+
+    @staticmethod
+    @lru_cache()
+    def get_embedding_client(
+        model: str = "text-embedding-3-small", dimensions: int = 384
+    ) -> OpenAIEmbeddings:
+        return OpenAIEmbeddings(model=model, dimensions=dimensions)
+
+
+class DevelopmentConfig(BaseConfig):
+    """
+    Development environment configuration settings.
+    """
+
+    Issuer = "https://trainwitharena.com"
+    Audience = "https://trainwitharena.com"
+    Domain = "trainwitharena.com"
+
+
+class ProductionConfig(BaseConfig):
+    """
+    Production environment configuration settings.
+    """
+
+    Issuer = "https://trainwitharena.com"
+    Audience = "https://trainwitharena.com"
+    Domain = "trainwitharena.com"
+
+
+@lru_cache()
+def get_settings() -> DevelopmentConfig | ProductionConfig:
+    """
+    Get the appropriate configuration based on the current environment.
+    """
+    config_cls_dict = {
+        "development": DevelopmentConfig,
+        "production": ProductionConfig,
+    }
+    config_name = os.getenv("FASTAPI_CONFIG", default="development")
+    config_cls = config_cls_dict[config_name]
+    return config_cls()  # type: ignore
+
+
+settings = get_settings()

cbh/core/database.py

@@ -0,0 +1,194 @@
+"""
+Database utilities for ClipboardHealthAI application.
+"""
+
+from datetime import datetime
+from enum import Enum
+import re
+from typing import Any, Dict, Type, TypeVar
+
+from bson import ObjectId
+from pydantic import AnyUrl, BaseModel, Field, GetCoreSchemaHandler
+from pydantic.json_schema import JsonSchemaValue
+from pydantic_core import core_schema
+
+T = TypeVar("T", bound=BaseModel)
+
+
+class PyObjectId:
+    """
+    Custom type for handling MongoDB ObjectId in Pydantic models.
+    """
+
+    @classmethod
+    def __get_pydantic_core_schema__(
+        cls, _source: type, _handler: GetCoreSchemaHandler
+    ) -> core_schema.CoreSchema:
+        """
+        Define the core schema for Pydantic validation.
+        """
+        return core_schema.with_info_after_validator_function(
+            cls.validate, core_schema.str_schema()  # type: ignore
+        )
+
+    @classmethod
+    def __get_pydantic_json_schema__(
+        cls, _schema: core_schema.CoreSchema, _handler: GetCoreSchemaHandler
+    ) -> JsonSchemaValue:
+        """
+        Define the JSON schema representation.
+        """
+        return {"type": "string"}
+
+    @classmethod
+    def validate(cls, value: str) -> ObjectId:
+        """
+        Validate and convert a string to MongoDB ObjectId.
+        """
+        if not ObjectId.is_valid(value):
+            raise ValueError(f"Invalid ObjectId: {value}")
+        return ObjectId(value)
+
+    def __getattr__(self, item):
+        """
+        Delegate attribute access to the wrapped ObjectId.
+        """
+        return getattr(self.__dict__["value"], item)
+
+    def __init__(self, value: str | None = None):
+        """
+        Initialize with a string value or create a new ObjectId.
+        """
+        if value is None:
+            self.value = ObjectId()
+        else:
+            self.value = self.validate(value)
+
+    def __str__(self):
+        """
+        Convert to string representation.
+        """
+        return str(self.value)
+
+
+class MongoBaseModel(BaseModel):
+    """
+    Base model for MongoDB documents with serialization support.
+    """
+
+    id: str = Field(default_factory=lambda: str(PyObjectId()))
+
+    class Config:  # pylint: disable=R0903
+        """
+        Configuration for the model.
+        """
+
+        arbitrary_types_allowed = True
+        extra = "ignore"
+        populate_by_name = True
+
+    @staticmethod
+    def serialize_s3_url(value: Any) -> Any:
+        """
+        Serialize an S3 URL.
+        """
+        if (
+            value
+            and isinstance(value, str)
+            and "AWSAccessKeyId" in value
+            and "Expires" in value
+        ):
+            match = re.search(r"s3\.amazonaws\.com/([^?]+)", value)
+            if match:
+                return match.group(1)
+        return value
+
+    def to_mongo(self) -> Dict[str, Any]:
+        """
+        Convert the model instance to a MongoDB-compatible dictionary.
+        """
+
+        def model_to_dict(model: BaseModel) -> Dict[str, Any]:
+            doc = {}
+            for name in model.__fields__.keys():
+                value = getattr(model, name)
+                key = model.__fields__[name].alias or name
+
+                if isinstance(value, BaseModel):
+                    doc[key] = model_to_dict(value)
+                elif isinstance(value, list) and all(
+                    isinstance(i, BaseModel) for i in value
+                ):
+                    doc[key] = [model_to_dict(item) for item in value]  # type: ignore
+                elif value and isinstance(value, Enum):
+                    doc[key] = value.value
+                elif isinstance(value, datetime):
+                    doc[key] = value.isoformat()  # type: ignore
+                elif value and isinstance(value, AnyUrl):
+                    doc[key] = str(value)  # type: ignore
+                else:
+                    doc[key] = self.serialize_s3_url(value)
+
+            return doc
+
+        result = model_to_dict(self)
+        return result
+
+    @classmethod
+    def from_mongo(cls, data: Dict[str, Any]):
+        """
+        Create a model instance from MongoDB document data.
+        """
+
+        def restore_enums(inst: Any, model_cls: Type[BaseModel]) -> None:
+            for name, field in model_cls.__fields__.items():  # type: ignore
+                value = getattr(inst, name)
+                if (
+                    field
+                    and isinstance(field.annotation, type)
+                    and issubclass(field.annotation, Enum)
+                ):
+                    setattr(inst, name, field.annotation(value))
+                elif isinstance(value, BaseModel):
+                    restore_enums(value, value.__class__)
+                elif isinstance(value, list):
+                    for i, item in enumerate(value):
+                        if isinstance(item, BaseModel):
+                            restore_enums(item, item.__class__)
+                        elif isinstance(field.annotation, type) and issubclass(
+                            field.annotation, Enum
+                        ):
+                            value[i] = field.annotation(item)
+                elif isinstance(value, dict):
+                    for k, v in value.items():
+                        if isinstance(v, BaseModel):
+                            restore_enums(v, v.__class__)
+                        elif isinstance(field.annotation, type) and issubclass(
+                            field.annotation, Enum
+                        ):
+                            value[k] = field.annotation(v)
+
+        if data is None:
+            return None
+        instance = cls(**data)
+        restore_enums(instance, instance.__class__)
+        return instance
+
+
+class MongoBaseShortenModel(BaseModel):
+    """
+    Base model for MongoDB documents with serialization support.
+    """
+
+    id: str
+
+    @classmethod
+    def to_mongo_fields(self) -> dict:
+        result = {field: 1 for field in self.__annotations__ if field != "_id"}
+        result["_id"] = 0
+        result["id"] = 1
+        return result
+
+    @classmethod
+    def from_mongo(cls, mongo_obj: Dict[str, Any]) -> T:
+        return cls(**mongo_obj)

cbh/core/email_client.py

@@ -0,0 +1,50 @@
+import re
+import asyncio
+import boto3
+
+
+class EmailClient:
+    def __init__(
+        self,
+        region: str,
+        sender_email: str,
+        sender_name: str,
+        profile_name: str | None = None,
+    ):
+        self.sender_email = sender_email
+        self.sender_name = sender_name
+        if profile_name:
+            session = boto3.Session(profile_name=profile_name)
+            self.ses_client = session.client("ses", region_name=region)
+        else:
+            self.ses_client = boto3.client("ses", region_name=region)
+
+    @staticmethod
+    def _strip_html(html_body: str) -> str:
+        text_body = re.sub("<[^<]+?>", "", html_body)
+        return text_body.replace("&nbsp;", " ").strip()
+
+    async def send_email(
+        self, recipient_email: str, subject: str, html_body: str
+    ) -> None:
+        text_body = self._strip_html(html_body)
+
+        def _send():
+            try:
+                return self.ses_client.send_email(
+                    Source=f"{self.sender_name} <{self.sender_email}>",
+                    Destination={"ToAddresses": [recipient_email]},
+                    Message={
+                        "Subject": {"Data": subject, "Charset": "UTF-8"},
+                        "Body": {
+                            "Text": {"Data": text_body, "Charset": "UTF-8"},
+                            "Html": {"Data": html_body, "Charset": "UTF-8"},
+                        },
+                    },
+                    ReplyToAddresses=[self.sender_email],
+                )
+            except Exception as exc:
+                print(f"Failed to send email: {exc}")
+                return None
+
+        await asyncio.to_thread(_send)

cbh/core/security.py

@@ -0,0 +1,199 @@
+"""
+Security utilities for ClipboardHealthAI application.
+
+This module provides authentication and authorization functionality, including:
+- Password verification
+- JWT token creation and validation
+- Permission-based endpoint protection using FastAPI dependencies
+"""
+
+from datetime import datetime, timedelta
+
+import anyio
+from fastapi import Depends, HTTPException
+from fastapi.security import HTTPAuthorizationCredentials, HTTPBearer
+from jose import JWTError, jwt
+from passlib.context import CryptContext
+
+from cbh.api.account.dto import AccountType
+from cbh.api.account.models import AccountModel
+from cbh.core.config import settings
+
+
+def verify_password(plain_password, hashed_password) -> bool:
+    """
+    Verify a password against its hashed version.
+
+    Args:
+        plain_password: The plain text password to verify
+        hashed_password: The hashed password to check against
+
+    Returns:
+        bool: True if the password matches, False otherwise
+    """
+    result = CryptContext(schemes=["bcrypt"], deprecated="auto").verify(
+        plain_password, hashed_password
+    )
+    return result
+
+
+def create_access_token(email: str, account_id: str, account_type: AccountType):
+    """
+    Create a JWT access token for a user.
+
+    Args:
+        email: User's email address
+        account_id: User's account ID
+        account_type: User's account type
+
+    Returns:
+        str: Encoded JWT token
+    """
+    payload = {
+        "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name": email,
+        "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier": account_id,
+        "accountId": account_id,
+        "accountType": account_type.value,
+        "iss": settings.Issuer,
+        "aud": settings.Audience,
+        "exp": datetime.utcnow() + timedelta(days=30),
+    }
+    encoded_jwt = jwt.encode(payload, settings.SECRET_KEY, algorithm="HS256")
+    return encoded_jwt
+
+
+class PermissionDependency:
+    """
+    FastAPI dependency for protecting endpoints with authentication.
+
+    This class implements the callable interface required for FastAPI dependencies
+    and validates JWT tokens for protected endpoints.
+    """
+
+    def __init__(
+        self, account_type: list[AccountType] | None = None, required: bool = True
+    ):
+        self.account_types = account_type
+        self.required = required
+
+    def __call__(
+        self,
+        credentials: HTTPAuthorizationCredentials | None = Depends(
+            HTTPBearer(auto_error=False)
+        ),
+    ) -> AccountModel | None:
+        """
+        Validate authorization credentials and return account details.
+
+        This method is called by FastAPI when the dependency is used.
+
+        Args:
+            credentials: The HTTP authorization credentials from the request
+
+        Returns:
+            AccountModel: The account details if authentication is successful
+
+        Raises:
+            HTTPException: If authentication fails
+        """
+        try:
+            if not credentials and self.required:
+                raise HTTPException(status_code=401, detail="Unauthorized")
+            elif not credentials and not self.required:
+                return None
+            account_id = self.authenticate_jwt_token(credentials.credentials)
+            account_data = anyio.from_thread.run(self.get_account_by_id, account_id)
+            self.check_account_health(account_data)
+            return AccountModel.from_mongo(account_data)
+
+        except JWTError as e:
+            raise HTTPException(  # pylint: disable=W0707
+                status_code=403, detail="Permission denied"
+            )
+        except Exception as e:
+            if isinstance(e, HTTPException) and e.status_code == 401:
+                raise e
+            raise HTTPException(  # pylint: disable=W0707
+                status_code=403, detail="Permission denied"
+            )
+
+    @staticmethod
+    async def get_account_by_id(account_id: str) -> dict:
+        """
+        Retrieve account data from the database by ID.
+
+        Args:
+            account_id: The account ID to look up
+
+        Returns:
+            dict: Account data from the database
+        """
+        account = await settings.DB_CLIENT.accounts.find_one({"id": account_id})
+        if not account:
+            raise HTTPException(status_code=403, detail="Permission denied")
+        return account
+
+    def check_account_health(self, account: dict):
+        """
+        Verify account data is valid and active.
+
+        Args:
+            account: Account data dictionary
+
+        Raises:
+            HTTPException: If the account is not valid
+        """
+        if not account:
+            raise HTTPException(status_code=403, detail="Permission denied")
+        if (
+            self.account_types
+            and AccountType(account["accountType"]) not in self.account_types
+        ):
+            raise HTTPException(status_code=403, detail="Permission denied")
+
+    @staticmethod
+    def authenticate_jwt_token(token: str) -> str:
+        """
+        Validate a JWT token and extract the account ID.
+
+        Args:
+            token: JWT token string
+
+        Returns:
+            str: Account ID from the token
+
+        Raises:
+            HTTPException: If token validation fails
+        """
+        payload = jwt.decode(
+            token, settings.SECRET_KEY, algorithms="HS256", audience=settings.Audience
+        )
+        email: str | None = payload.get(
+            "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
+        )
+        account_id: str | None = payload.get("accountId")
+
+        if email is None or account_id is None:
+            raise HTTPException(status_code=403, detail="Permission denied")
+
+        return account_id
+
+
+def check_account_token(token: str) -> dict | None:
+    try:
+        payload = jwt.decode(
+            token, settings.SECRET_KEY, algorithms="HS256", audience=settings.Audience
+        )
+        email: str | None = payload.get(
+            "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name"
+        )
+        account_id: str | None = payload.get("accountId")
+        if email is None or account_id is None:
+            return None
+        return {
+            "email": email,
+            "account_id": account_id,
+            "account_type": payload.get("accountType"),
+        }
+    except Exception as _:
+        return None

cbh/core/wrappers.py

@@ -0,0 +1,119 @@
+"""
+Response wrappers and utility decorators for ClipboardHealthAI application.
+
+This module provides:
+- Standardized response wrappers for API endpoints
+- Exception handling decorators
+- OpenAI API request wrapper
+- Background task decorator
+"""
+
+from functools import wraps
+from typing import Generic, Optional, TypeVar
+
+from fastapi import HTTPException
+from pydantic import BaseModel
+from starlette.responses import JSONResponse
+
+T = TypeVar("T")
+
+
+class ErrorCbhResponse(BaseModel):
+    """
+    Error response model for standardized error formatting.
+
+    Attributes:
+        message: Error message describing what went wrong
+    """
+
+    message: str
+
+
+class CbhResponseWrapper(BaseModel, Generic[T]):
+    """
+    Standard response wrapper for all API endpoints.
+
+    This class provides a consistent structure for all API responses,
+    including data, success status, and error information.
+
+    Attributes:
+        data: The response data (optional)
+        successful: Whether the request was successful
+        error: Error details if the request failed
+    """
+
+    data: Optional[T] = None
+    successful: bool = True
+    error: Optional[ErrorCbhResponse] = None
+
+    def response(self, status_code: int):
+        """
+        Create a JSONResponse with proper status code and formatting.
+
+        Args:
+            status_code: HTTP status code for the response
+
+        Returns:
+            JSONResponse: Formatted API response
+        """
+        return JSONResponse(
+            status_code=status_code,
+            content={
+                "data": self.data,
+                "successful": self.successful,
+                "error": self.error.dict() if self.error else None,
+            },
+        )
+
+
+def exception_wrapper(http_error: int, error_message: str):
+    """
+    Decorator for handling exceptions in route handlers.
+
+    Catches any exceptions and converts them to a proper HTTP exception
+    with specified status code and error message.
+
+    Args:
+        http_error: HTTP status code to use for the exception
+        error_message: Error message to include
+
+    Returns:
+        Decorator function that wraps route handlers
+    """
+
+    def decorator(func):
+        @wraps(func)
+        async def wrapper(*args, **kwargs):
+            try:
+                return await func(*args, **kwargs)
+            except Exception as e:
+                raise HTTPException(status_code=http_error, detail=error_message) from e
+
+        return wrapper
+
+    return decorator
+
+
+def background_task():
+    """
+    Decorator for background tasks that should not crash the application.
+
+    Wraps a function to catch and suppress any exceptions, preventing
+    background task failures from affecting the main application.
+
+    Returns:
+        Decorator function for background tasks
+    """
+
+    def decorator(func):
+        @wraps(func)
+        async def wrapper(*args, **kwargs) -> str | None:
+            try:
+                result = await func(*args, **kwargs)
+                return result
+            except Exception:  # pylint: disable=W0718
+                return None
+
+        return wrapper
+
+    return decorator

main.py

@@ -0,0 +1,10 @@
+"""
+FastAPI application entry point for ClipboardHealthAI.
+
+This file creates and launches the FastAPI application by importing the create_app
+function from the cbh package.
+"""
+
+from cbh import create_app
+
+app = create_app()

test_main.http

@@ -0,0 +1,11 @@
+# Test your FastAPI endpoints
+
+GET http://127.0.0.1:8000/
+Accept: application/json
+
+###
+
+GET http://127.0.0.1:8000/hello/User
+Accept: application/json
+
+###