DEV Community: Nazmus Saqueeb Ashrafi

OAuth2 Email Account Connection and Securely Integrating Microsoft Outlook: Email Agent Series - Part 2

Nazmus Saqueeb Ashrafi — Mon, 01 Dec 2025 18:03:20 +0000

A technical deep dive into implementing secure OAuth2 authentication with encrypted token storage

Introduction

Connecting users' email accounts is the core feature of the AI Email Coach. This article details the implementation of the OAuth2 Authorization Code Flow to securely connect Microsoft Outlook accounts. We'll explore how we handle the complex dance between our frontend, backend, and Microsoft's identity servers, while ensuring sensitive tokens are never exposed or stored in plaintext.

We'll cover:

The OAuth2 Handshake: From "Connect" button to success callback
Security First: CSRF protection with state and Fernet token encryption
Backend Architecture: Handling callbacks and token exchange
Frontend Experience: Seamless redirection and error handling

System Overview

The connection flow involves three parties:

User's Browser (Frontend)
Our API Server (Backend)
Microsoft Identity Platform (External Provider)

High-Level Sequence

Figure 1: High-level sequence diagram of the Email Account Connection Process

Part 1: Initiating the Flow

The Frontend Trigger

Figure 2: Frontend architecture showing the flow from UI component - how the backend route is hit and the token is passed from local storage to the backend

The process begins in ConnectAccountButton.tsx. Unlike typical API calls, this triggers a browser redirection.

// webapp/frontend/components/accounts/connect-account-button.tsx
export function ConnectAccountButton() {
    const handleConnectOutlook = () => {
        const token = tokenManager.get();
        if (!token) return;

        // Redirect to backend to start the dance
        // We pass the JWT token so the backend knows WHO is connecting
        const oauthUrl = `${emailAccountsClient.getOAuthUrl()}?token=${encodeURIComponent(token)}`;
        // Triggers the Backend Route `/api/email_accounts/oauth/authorize`
        window.location.href = oauthUrl;
    };
    // ... Button UI
}

Why Is encodeURIComponent Used?

encodeURIComponent makes the token URL-safe before adding it to a query string.

Tokens may contain special characters (/, =, &, ?, +) that can break a URL or be misinterpreted as new parameters. Encoding converts these characters into a safe format so the token is transmitted exactly as intended.

Example

Raw token:

abc123/=/xyz&role=admin

Encoded:

abc123%2F%3D%2Fxyz%26role%3Dadmin

In short:

Encoding protects the token and ensures the OAuth server receives the correct value.

Figure 3: Backend architecture showing Part 1: Building the Authorization URL

Backend Part 1: Building the Authorization URL

The backend endpoint /api/email_accounts/oauth/authorize does the heavy lifting of preparing the request to Microsoft.

Key Security Feature: The state Parameter
We don't just send the user to Microsoft; we pack a secure "state" token to prevent Cross-Site Request Forgery (CSRF).

# webapp/backend/email_accounts/service.py
def create_oauth_state(user_id: UUID) -> str:
    """
    Create a secure state parameter.
    Encodes user_id and timestamp for CSRF protection.
    """
    state_data = {
        "user_id": str(user_id),
        "timestamp": datetime.now(timezone.utc).isoformat(),
        "nonce": secrets.token_urlsafe(32)
    }
    return json.dumps(state_data)

The router then constructs the Microsoft URL and redirects the user:

# webapp/backend/email_accounts/router.py
@router.get("/oauth/authorize")
async def oauth_authorize(token: str, db: Session):
    # 1. Verify the user's JWT
    token_data = verify_token(token)
    user_id = token_data.get_uuid()

    # 2. Generate secure state
    state = service.create_oauth_state(user_id)

    # 3. Build Microsoft URL
    # https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?...
    auth_url = app.get_authorization_request_url(
        scopes=["User.Read", "Mail.ReadWrite", "Mail.Send"],
        state=state,
        redirect_uri=settings.MICROSOFT_REDIRECT_URI
    )

    # 4. Redirect user
    return RedirectResponse(url=auth_url)

Backend Part 2: Handling the Callback

Figure 4: Backend architecture showing Part 2: Handling the Callback

After the user logs in at Microsoft, they are redirected back to our application. This is where the critical exchange happens.

The Callback Endpoint

The endpoint /api/email_accounts/oauth/callback receives the code (authorization code) and state from Microsoft.

Step 1: Verify State \
First, we ensure this is a legitimate response to a request we initiated.

# webapp/backend/email_accounts/service.py
def verify_oauth_state(state: str, max_age_minutes: int = 10) -> Optional[UUID]:
    data = json.loads(state)

    # Check expiration
    timestamp = datetime.fromisoformat(data["timestamp"])
    if age > timedelta(minutes=max_age_minutes):
        return None

    return UUID(data["user_id"])

Step 2: Exchange Code for Tokens \
We trade the temporary code for long-lived tokens.

# webapp/backend/email_accounts/service.py
def exchange_code_for_tokens(code: str) -> dict:
    app = get_msal_app()
    result = app.acquire_token_by_authorization_code(
        code=code,
        scopes=settings.MICROSOFT_SCOPES,
        redirect_uri=settings.MICROSOFT_REDIRECT_URI
    )
    return result
    # Returns: { "access_token": "...", "refresh_token": "...", ... }

Step 3: Identify the Account \
We use the new access token to fetch the user's profile from Microsoft Graph (/me) to get their email address. This ensures we link the correct email account.

Part 3: Secure Storage (Encryption)

We never store tokens in plaintext. If our database were compromised, attackers could access users' emails. Instead, we use Fernet symmetric encryption.

Encryption Service

# webapp/backend/email_accounts/service.py
from cryptography.fernet import Fernet

def encrypt_token(token: str) -> str:
    cipher = Fernet(settings.TOKEN_ENCRYPTION_KEY.encode())
    return cipher.encrypt(token.encode()).decode()

def decrypt_token(encrypted_token: str) -> str:
    cipher = Fernet(settings.TOKEN_ENCRYPTION_KEY.encode())
    return cipher.decrypt(encrypted_token.encode()).decode()

Database Entity

The EmailAccount entity stores the encrypted blob.

# webapp/backend/entities/email_account.py
class EmailAccount(Base):
    # ...
    provider = Column(Enum(ProviderEnum), nullable=False)
    email_address = Column(String, nullable=False)

    # 🔒 Encrypted storage
    ms_refresh_token_encrypted = Column(String, nullable=True)

    # We don't store access tokens permanently as they expire quickly
    access_token_expires_at = Column(DateTime(timezone=True))

Part 4: Frontend Feedback Loop

The backend redirects the browser to the frontend's callback page with a status parameter:
http://localhost:3000/accounts/oauth-callback?success=true

The OAuthCallbackPage component handles the final UX:

// webapp/frontend/app/accounts/oauth-callback/page.tsx
export default function OAuthCallbackPage() {
    const searchParams = useSearchParams();

    useEffect(() => {
        if (searchParams.get('success')) {
            setMessage('Account connected successfully!');
            // Auto-redirect to dashboard
            setTimeout(() => router.push('/accounts'), 2000);
        } else {
            setMessage('Connection failed.');
        }
    }, [searchParams]);

    // Renders a nice success/error UI card
}

Security Checklist

✅ CSRF Protection: The state parameter binds the request to the user session and ensures the callback is for the request we sent. \
✅ Encryption at Rest: Refresh tokens are encrypted using Fernet (AES-128-CBC) before hitting the database. \
✅ Short-lived Access: We only hold the access token in memory during the request or for short durations. We rely on the refresh token to get new ones. \
✅ Scope Minimization: We only request scopes we need (Mail.ReadWrite, Mail.Send).

Common Pitfalls & Solutions

"Invalid State" Error:
- Cause: User took too long (>10 mins) or browser blocked cookies.
- Fix: Retry the flow. The timestamp in the state ensures requests expire.
Token Encryption Errors:
- Cause: Changing the TOKEN_ENCRYPTION_KEY in .env.
- Fix: Once keys are rotated, old tokens become unreadable. Key management is critical.
Redirect URI Mismatch:
- Cause: The URI in the code doesn't match what's registered in Azure Portal.
- Fix: Ensure MICROSOFT_REDIRECT_URI matches exactly in both .env and Azure.

Design Strengths & Potential Issues

Strengths:

✅ State parameter validation (CSRF protection)
State contains the user_id and is unique per request
Even if attacker intercepts the callback URL, the state is tied to attacker's session, not victim's
✅ Error handling throughout using RedirectResponse.
All failure paths redirect gracefully to frontend
✅ HTTPS required (implicit in OAuth 2.0)
OAuth 2.0 spec requires HTTPS for redirect URIs
Microsoft won't allow http:// callbacks in production
Prevents man-in-the-middle attacks intercepting tokens
✅ Duplicate account checking
Before saving, we check if the email already exists in the database
Prevents same email being added twice by same user

Potential Issues: (To Be Solved Later)

⚠️ Synchronous HTTP call: httpx.get() is blocking (should use async httpx.AsyncClient)

# Current (BLOCKING):
graph_response = httpx.get(
    "https://graph.microsoft.com/v1.0/me",
    headers=headers,
    timeout=10.0
)

The problem:

The function is async def but uses synchronous httpx.get()
Blocks the entire event loop for up to 10 seconds
If 100 users OAuth simultaneously, they wait in queue instead of concurrently (CRITICAL)

Access token not stored: Only refresh token is saved, so immediate API calls need token refresh
The access token expires quickly (1 hour)
We need to refresh it every hour
This adds complexity to the code (not needed)
State token lifetime: No visible timeout (should expire in 5-10 minutes)

If user takes 11 minutes to authorize, they get a cryptic error
User experience issue:
- User clicks "Connect Outlook" → goes to Microsoft → takes coffee break → returns → "Invalid state" error
- Should show: "Session expired. Please try connecting again."
No retry logic: Microsoft Graph call could fail transiently

The problem:

Network blip or Microsoft temporary outage = entire OAuth fails
User has to restart the whole flow

Conclusion

This flow provides a robust, secure foundation for the Email Coach. By handling the complexity of OAuth2 and encryption in the backend, we keep the frontend simple and the user data safe. This connected account is now ready for Delta Sync.

Understanding User Registration: Email Agent Series - Part 1

Nazmus Saqueeb Ashrafi — Sun, 30 Nov 2025 16:12:36 +0000

A deep dive into building secure, scalable user registration with React, FastAPI, and modern authentication patterns

Introduction

User registration is the gateway to any application. It's the first interaction users have with your system, and it sets the tone for security, user experience, and architectural quality. In this article, I'll walk you through the complete user registration flow in my AI Email Assistant application, from the moment a user clicks "Register" to when their encrypted credentials are safely stored in the database.

We'll explore:

Frontend architecture with React Context and custom hooks
Backend API design with FastAPI and Pydantic validation
Security best practices including bcrypt password hashing
Clean architecture patterns that promote maintainability and testability

System Overview

The registration flow spans multiple layers of abstraction, each with a specific responsibility:

Frontend Stack:

Next.js 14 (React with TypeScript)
React Context for global state management
Custom hooks for clean component APIs
Layered API client architecture

Backend Stack:

FastAPI (Python)
SQLAlchemy ORM
Pydantic for data validation
bcrypt for password hashing
JWT for authentication tokens

The Complete Flow at a Glance

Before diving into the details, let's visualize the high-level journey:

Figure 1: High-level sequence diagram of the registration process

Key Steps:

User Input → Form submission with validation
Frontend → Three-layer architecture (UI → Context → API Client)
HTTP Request → POST to backend with user data
Backend Validation → Pydantic schema checks
Password Security → bcrypt hashing with salt
Database → User record persisted
Auto-Login → Seamless authentication
Redirect → User sent to dashboard

Part 1: Frontend Architecture

The Three-Layer Abstraction

One of the key architectural decisions in this application is the separation of concerns on the frontend. Instead of making direct API calls from UI components, the registration flow passes through three distinct layers:

UI Component Layer - User interaction and form state
Context Layer - Global state management and business logic
API Client Layer - HTTP communication and token management

This architecture provides several benefits:

Reusability: Auth functions available throughout the app
Testability: Each layer can be tested in isolation
Maintainability: Changes to API structure only affect one file
Type Safety: TypeScript ensures correctness across layers

Frontend Flow Diagram

Figure 2: Frontend architecture showing the flow from UI component through Context and API clients to the backend

Layer 1: The Registration Page Component

The registration page is a client-side React component that manages form state and user interaction.

// webapp/frontend/app/auth/register/page.tsx
export default function RegisterPage() {
  const router = useRouter();
  const { register } = useAuth(); // Custom hook from AuthContext

  const [formData, setFormData] = useState({
    email: '',
    first_name: '',
    last_name: '',
    password: '',
    confirmPassword: '',
  });

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();

    // Client-side validation
    const validationError = validateForm();
    if (validationError) {
      setError(validationError);
      return;
    }

    try {
      // Call register from context - clean and simple!
      await register({
        email: formData.email,
        first_name: formData.first_name,
        last_name: formData.last_name,
        password: formData.password,
      });

      // Auto-login successful, redirect to dashboard
      router.push('/accounts');

    } catch (err: any) {
      setError(err.message || 'Registration failed');
    }
  };
}

Key Observations:

No HTTP details in the component - it just calls register()
Clean separation between UI logic and API communication
Error handling is straightforward and user-friendly

Layer 2: Authentication Context Provider

The Auth Context is where the magic happens. It's a React Context Provider that manages global authentication state and provides auth functions to all components.

// webapp/frontend/components/auth/auth-context.tsx
export function AuthProvider({ children }: { children: React.ReactNode }) {
  const [user, setUser] = useState<User | null>(null);
  const [isLoading, setIsLoading] = useState(true);

  /**
   * Register new user and auto-login
   */
  const register = useCallback(async (data: RegisterData) => {
    setIsLoading(true);
    try {
      // Step 1: Register user
      await authClient.register(data);

      // Step 2: Auto-login after successful registration
      await login({ email: data.email, password: data.password });

    } catch (error) {
      setIsLoading(false);
      throw error;
    }
  }, [login]);

  return (
    <AuthContext.Provider value={{ user, register, login, logout }}>
      {children}
    </AuthContext.Provider>
  );
}

// Custom hook for easy access
export function useAuth() {
  const context = useContext(AuthContext);
  if (!context) {
    throw new Error('useAuth must be used within AuthProvider');
  }
  return context;
}

Why Use Context?

Global State: Authentication state available everywhere in the app (ie. Shared data across multiple components)
Avoid Prop Drilling: No need to pass auth functions through multiple components
Single Source of Truth: One place manages all authentication logic
Auto-Login Feature: Seamless UX - users are logged in immediately after registration

Why Wrap Context in a Custom Hook (useAuth)?

The useAuth() custom hook is a convenience wrapper around useContext(AuthContext). It has the CONSUMER which can consume the AuthContext PROVIDER. While we could use useContext(AuthContext) directly in components, the custom hook provides several advantages:

Cleaner API: Components call useAuth() instead of useContext(AuthContext) - shorter and more semantic
Error Handling: The hook throws a helpful error if used outside AuthProvider, catching mistakes early
Type Safety: TypeScript knows the exact return type, providing better autocomplete
Encapsulation: Implementation details hidden - we could change the underlying mechanism without affecting components
Consistency: Standard React pattern - most Context APIs provide custom hooks (e.g., useRouter, useTheme)

Example:

// Without custom hook (verbose, no error checking)
const context = useContext(AuthContext);
if (!context) throw new Error('...');
const { register } = context;

// With custom hook (clean, safe)
const { register } = useAuth();

This pattern is so common in React that it's considered a best practice for any Context API.

Layer 3: API Client Architecture

The API client layer is split into two files:

auth-client.ts - Authentication-specific API calls:

export const authClient = {
  register: async (data: RegisterData): Promise<void> => {
    await api.post('/api/auth/register', data);
  },

  login: async (credentials: LoginCredentials): Promise<AuthTokens> => {
    // OAuth2 password flow
    const formData = new URLSearchParams();
    formData.append('username', credentials.email);
    formData.append('password', credentials.password);

    const response = await fetch(/* ... */);
    const tokens = await response.json();

    // Store JWT token
    tokenManager.set(tokens.access_token);
    return tokens;
  },
};

api-client.ts - Base HTTP client with automatic token injection:


// BLOCK 1

export async function apiClient<T>(
  endpoint: string,
  options: RequestOptions = {}
): Promise<T> {
  const config: RequestInit = {
    method: options.method || 'GET',
    headers: {
      'Content-Type': 'application/json',
      ...options.headers,
    },
  };

  // Auto-inject JWT token for protected endpoints
  if (options.requiresAuth) {
    const token = getAuthToken();
    if (token) {
      config.headers.Authorization = `Bearer ${token}`;
    }
  }

  const response = await fetch(`${API_BASE_URL}${endpoint}`, config);

  // Centralized error handling
  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.detail || 'Request failed');
  }

  return response.json();
}


// BLOCK 2

// ❌ WITHOUT apiClient - Repetitive nightmare
async function getUser() {
  const token = localStorage.getItem('auth_token');
  const response = await fetch('http://localhost:8000/api/users/me', {
    method: 'GET',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`,
    },
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.detail || 'Request failed');
  }

  return response.json();
}

async function updateUser(data) {
  const token = localStorage.getItem('auth_token');
  const response = await fetch('http://localhost:8000/api/users/me', {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${token}`,
    },
    body: JSON.stringify(data),
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.detail || 'Request failed');
  }

  return response.json();
}

// ... repeat this 50 times for every endpoint


// BLOCK 3

// ✅ WITH apiClient - Clean and reusable
async function getUser() {
  return apiClient('/api/users/me', { requiresAuth: true });
}

async function updateUser(data) {
  return apiClient('/api/users/me', { 
    method: 'PUT', 
    requiresAuth: true,
    body: data 
  });
}

Benefits of using the apiClient:

DRY (Do not repeat yourself) Principle: All API calls use the same base client - See code BLOCK 2 and 3 above
Automatic Token Injection: Protected endpoints get JWT automatically - See code BLOCK 1 above
Centralized Error Handling: Consistent error messages across the app - See code BLOCK 1 above
Type Safety: TypeScript generics ensure type correctness - See code BLOCK 1 above

Part 2: Backend Architecture

The Service Layer Pattern

The backend follows a clean Router → Service → Database pattern:

Router: HTTP layer - handles requests and responses
Service: Business logic - validation, password hashing, database operations
Database: Data persistence - SQLAlchemy models

This separation ensures that business logic is decoupled from HTTP concerns, making it easier to test and maintain.

Backend Flow Diagram

Figure 3: Backend architecture showing the flow from API endpoint through validation, service layer, and database operations

The Router: API Endpoint Definition

The router is the entry point for HTTP requests. It defines the endpoint and delegates to the service layer.

# webapp/backend/auth/router.py
from fastapi import APIRouter, Depends
from sqlalchemy.orm import Session

router = APIRouter(prefix='/auth', tags=['auth'])

@router.post("/register", status_code=status.HTTP_201_CREATED)
async def register_user(
    db: Annotated[Session, Depends(get_db)],
    register_user_request: schemas.RegisterUserRequest
):
    """
    Register a new user

    - **email**: Valid email address (must be unique)
    - **first_name**: User's first name
    - **last_name**: User's last name
    - **password**: User's password (will be hashed)
    """
    service.register_user(db, register_user_request)
    return {"message": "User registered successfully"}

Key Features:

Dependency Injection: Database session injected automatically
Pydantic Validation: Request body validated against schema
Status Code: Returns 201 Created (REST convention)
Clean Separation: Router handles HTTP, service handles logic

Pydantic Schema: Request Validation

Pydantic schemas define the shape and validation rules for request data.

# webapp/backend/auth/schemas.py
from pydantic import BaseModel, EmailStr

class RegisterUserRequest(BaseModel):
    """Request model for user registration"""
    email: EmailStr
    first_name: str
    last_name: str
    password: str

What Pydantic Does:

Email Validation: Checks format (e.g., user@example.com)
Type Checking: Ensures all fields are correct types
Automatic Parsing: Converts JSON to Python objects
Error Messages: Returns detailed validation errors

If validation fails, FastAPI automatically returns a 422 Unprocessable Entity response with details about what went wrong.

Service Layer: Business Logic

The service layer contains the core registration logic, including password hashing and database operations.

# webapp/backend/auth/service.py
from passlib.context import CryptContext
from uuid import uuid4

bcrypt_context = CryptContext(schemes=['bcrypt'], deprecated='auto')

def get_password_hash(password: str) -> str:
    """Hash a plain password using bcrypt"""
    return bcrypt_context.hash(password)

def register_user(db: Session, register_user_request: schemas.RegisterUserRequest):
    """
    Register a new user
    Raises UserAlreadyExistsError if email is already registered
    """
    try:
        # Create User model with hashed password
        create_user_model = User(
            id=uuid4(),  # Generate unique UUID
            email=register_user_request.email,
            first_name=register_user_request.first_name,
            last_name=register_user_request.last_name,
            password_hash=get_password_hash(register_user_request.password)
        )

        # Add to database and commit
        db.add(create_user_model)
        db.commit()

        logging.info(f"Successfully registered user: {register_user_request.email}")

    except IntegrityError:
        # Email already exists (UNIQUE constraint violation)
        db.rollback()
        raise UserAlreadyExistsError()

Critical Security Feature: bcrypt Password Hashing

The password is never stored in plain text. Instead, it's hashed using bcrypt:

Input:  "securepass123"
Output: "$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewY5GyYzS7eFa.oi"

Why bcrypt?

Salted: Automatically adds random salt (prevents rainbow table attacks)
Adaptive: Can increase cost factor as computers get faster
One-way: Cannot reverse hash to get original password
Industry Standard: Used by GitHub, Facebook, and other major platforms

Database Model: SQLAlchemy Schema

The User model defines the database table structure.

# webapp/backend/entities/users.py
from sqlalchemy import Column, String, DateTime, UUID
from datetime import datetime, timezone

class User(Base):
    __tablename__ = 'users'

    id = Column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
    email = Column(String, unique=True, nullable=False)
    first_name = Column(String, nullable=False)
    last_name = Column(String, nullable=False)
    password_hash = Column(String, nullable=False)
    created_at = Column(DateTime(timezone=True), default=lambda: datetime.now(timezone.utc))
    updated_at = Column(DateTime(timezone=True), onupdate=lambda: datetime.now(timezone.utc))

    # Relationships
    email_accounts = relationship("EmailAccount", back_populates="user", cascade="all, delete-orphan")

Database Constraints:

Primary Key: UUID (globally unique, secure)
Unique Email: Database enforces uniqueness
Not Null: All required fields enforced at DB level
Cascade Delete: Deleting user deletes all related email accounts

Security Considerations

Defense in Depth

Security is implemented at multiple layers:

1. Frontend Validation

Client-side checks for immediate feedback
Password length requirements (minimum 8 characters)
Password confirmation matching

2. Backend Validation

Pydantic schema validation (type checking, email format)
Database constraints (unique email, not null)

3. Password Security

bcrypt hashing with automatic salting
Cost factor of 12 (2^12 = 4096 iterations)
Never logged or displayed in plain text

4. SQL Injection Prevention

SQLAlchemy ORM automatically parameterizes queries
No raw SQL with user input

5. Token Security

JWT tokens for stateless authentication
Tokens stored in localStorage (HTTPS in production)
Automatic expiration (30 days)

Error Handling

The system handles errors gracefully at every layer:

Email Already Exists

HTTP 400 Bad Request
{
  "detail": "User with this email already exists"
}

Invalid Email Format

HTTP 422 Unprocessable Entity
{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "value is not a valid email address",
      "type": "value_error.email"
    }
  ]
}

Missing Required Field

HTTP 422 Unprocessable Entity
{
  "detail": [
    {
      "loc": ["body", "first_name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

The Auto-Login Feature

One of the UX improvements in this implementation is automatic login after registration. Here's how it works:

User submits registration form
Backend creates account successfully
Frontend Auth Context automatically calls login() with the same credentials
JWT token is retrieved and stored
User state is updated globally
User is redirected to /accounts dashboard

Benefits:

Seamless UX: No need to manually log in after registering
Fewer Steps: Reduces friction in onboarding flow
Immediate Value: User can start using the app right away

Testing the Flow

Manual Testing Steps

Start Backend:

   cd webapp/backend
   uv run main.py

Start Frontend:

   cd webapp/frontend
   npm run dev

Navigate to Registration:

   http://localhost:3000/auth/register

Fill Form:
- Email: test@example.com
- First Name: Test
- Last Name: User
- Password: password123
- Confirm Password: password123
Verify:
- Check console logs for success
- Verify redirect to accounts page
- Check database for new user record

Database Verification

sqlite3 webapp/backend/databse.db

SELECT id, email, first_name, last_name, created_at 
FROM users 
WHERE email = 'test@example.com';

Performance Considerations

Password Hashing Cost

The bcrypt cost factor is set to 12, which provides a good balance:

Cost 10: ~100ms (too fast, less secure)
Cost 12: ~250ms (current setting, recommended)
Cost 14: ~1000ms (too slow for user experience)

Database Indexing

The email field has a unique index for fast lookups:

CREATE UNIQUE INDEX idx_users_email ON users(email);

This ensures O(log n) search time for email lookups during login.

Lessons Learned

What Worked Well

✅ Layered Architecture: Clean separation of concerns made the code maintainable and testable

✅ React Context: Global auth state eliminated prop drilling and simplified components

✅ Pydantic Validation: Automatic validation saved time and caught errors early

✅ bcrypt Hashing: Industry-standard security with minimal implementation effort

✅ Auto-Login: Improved UX significantly with minimal code

What Could Be Improved

🔄 Add Unit Tests: Currently no automated tests for registration flow

🔄 Rate Limiting: Prevent brute-force registration attempts

🔄 Email Verification: Send confirmation email before activating account

🔄 Password Strength Meter: Visual feedback on password quality

🔄 CAPTCHA: Prevent automated bot registrations

Conclusion

Building a secure, user-friendly registration flow requires attention to detail at every layer of the stack. By following clean architecture principles, implementing security best practices, and focusing on user experience, we've created a registration system that is:

Secure: bcrypt hashing, SQL injection prevention, multiple validation layers
Maintainable: Clear separation of concerns, type safety, reusable components
User-Friendly: Auto-login, clear error messages, responsive validation
Scalable: Stateless JWT authentication, efficient database queries

The key takeaway is that good architecture pays dividends. The three-layer frontend abstraction and the router-service-database pattern on the backend make the code easy to understand, test, and extend.

Whether you're building a simple side project or a production application, these patterns and practices will serve you well.

Code Repository

The complete source code for this implementation is available in my AI Email Coach project:

Frontend: webapp/frontend/app/auth/register/
Backend: webapp/backend/auth/
Database Models: webapp/backend/entities/users.py

Written by Nazmus Ashrafi | Built with Next.js, FastAPI, and ❤️

Full Source: Available in private repository upon request
Please contact me for access: nazmus.s.ashrafi@gmail.com

React basics - useState and Prop drilling

Nazmus Saqueeb Ashrafi — Tue, 19 Jul 2022 23:49:25 +0000

This article will discuss some of the core features of React. I have managed to get a grasp of few concepts within React by making a simple application (A color choser). This article will describe the concepts by explaining how the app was made.

There are four concepts which will be discussed in this article:

React functional components
useState hook
Controlled input
Prop drilling

React functional components

Modern React uses functional components. In making this color choser application, two components are used which are being imported to the App.js main component. These components are:

The Box component
The Input component

// The App.js main component

import Box from "./Box";
import Input from "./Input";

function App() {
  return (
    <div className="App">
      <Box />
      <Input />
    </div>
  );
}

export default App;

// The Input component

const Input = () => {
  return <input autoFocus placeholder="Enter color here" />;
};

export default Input;

// The Box component

const Box = () => {

  return (
    <div>
      <div style={
          margin:'auto',
          width:'500px',
          height:'100px',
          border:'1px solid #000',
          textAlign: 'center',
          backgroundColor: green
      }></div>

    </div>

  )

};

export default Box;

Notice that the default color of the Box component is set to green. We will use a useState hook to avoid hardcoding the background color in the next section.

useState hook

We will use the useState hook to set an initial color of empty. The idea is to take input from the user to set the color. The user input will then be used to change the color of the box in the next section.

import Box from "./Box";
import Input from "./Input";

import React, { useState } from "react";

function App() {
  const [color, setColor] = useState("");

  return (
    <div className="App">
      <Box />
      <Input />
    </div>
  );
}

export default App;

Controlled input and prop drilling

The useState hook and onChange function will be written in the main App.js component which acts as the parent component in our app. We will drill these properties down to our children components. This way the Box and Input components can use the useState hook and onChange function.

Also notice what our onChange function does. It takes takes the value from the event and uses the hook to change the value of the color. We will also set the value of the event using the user input. The value of the input is also set to color which is the hook. This will make our input a controlled input.

import Box from "./Box";
import Input from "./Input";

import React, { useState } from "react";

function App() {
  const [color, setColor] = useState("");

  const onChange = (e) => {
    setColor(e.target.value);
  };

  return (
    <div className="App">
      <Box color={color} />
      <Input onChange={onChange} color={color} />
    </div>
  );
}

export default App;

const Input = ({ onChange, color }) => {
  return (
    <input
      autoFocus
      onChange={onChange}
      placeholder="Enter color here"
      value={color}
    />
  );
};

export default Input;


const Box = ({color}) => {


  return (
    <div>
      <div style={
          margin:'auto',
          width:'500px',
          height:'100px',
          border:'1px solid #000',
          textAlign: 'center',
          backgroundColor: color
      }>{color?color:"This is empty"}</div>

    </div>

  )

};

export default Box;

Bootstrap vs Tailwind

Nazmus Saqueeb Ashrafi — Wed, 13 Jul 2022 08:43:22 +0000

Has anyone here used Bootstrap? If so, how difficult is it to learn to use? I'd love to be able to just assign a class to get the effect I want without having to mess with a bunch of CSS properties. Heard a lot of positives about it. How is it compared to Tailwind?
Give me advice on the best way to CSS currently. Thanks.