Wednesday, March 5, 2025

Converting a web app to mobile

If you have a responsive web app, you could convert it to a mobile app using React Native WebView without writing any additional mobile code. However, there may be challenges with getting approval from both Google Play and the Apple App Store when using a WebView wrapper approach:
  1. Apple App Review Guidelines Rule 4.2 explicitly states that apps should include features, content, and UI elements that elevate them beyond being just a repackaged website.
  2. Google Play Store: While generally more lenient than Apple, Google still requires apps to provide a reasonably engaging user experience.
The more native integration you include, the more likely you are to pass the review process. Potential Solutions:
  1. Add native functionality such as push notifications or device camera integration.
  2. Implement offline capabilities that aren't available in the web version.
The easiest way to convert your web app to mobile is to ask claude.ai to do it. Your job would be to review, refactor, test and debug the generated mobile code.

Monday, February 10, 2025

Memory cost of image conversion

In my web app, users can upload images as PNG, JPEG etc. I convert them to WebP because it uses much less space on disk and loads faster in web page requests. However, conversion uses raw pixels, so the memory (RAM) required is almost irrelevant to the original file size because file size depends on the compression of raw pixels. The memory needed is primarily determined by: Width * Height * Bytes per pixel. 

A PNG needs 3 bytes for RGB and 1 byte for alpha = 4 bytes per pixel. For a 5637x5637 PNG with RGBA colors, we need 5637 * 5637 * 4 bytes per pixel = ~127MB just for the uncompressed pixel data alone. The file size of that PNG is 6MB.

JPEG files typically don't have an alpha channel, so they need 3 bytes per pixel. For a 5637x5637 JPEG, memory needed would be 5637 * 5637 * 3 = ~95MB. The actual file size of the JPEG could range from:

  • High quality (90%): 2-8MB
  • Medium quality (70%): 1-4MB
  • Low quality (50%): 500KB-2MB
When setting upload limits for image processing, you should primarily consider the image dimensions (megapixels) rather than the file size (megabytes). Here's why:

  1. A user could upload a highly compressed 2MB PNG that's 10000x10000 pixels - this would need ~400MB RAM to process.
  2. Another user could upload a poorly compressed 10MB JPEG that's 1000x1000 pixels - this would only need ~3MB RAM to process.

Considering that current mobile cameras can typically capture 16MP images, the decompressed image would require approximately 16e6 pixels × 4 bytes/pixel / 1024 / 1024 = 61MB of memory. Additional couple of MB memory may be needed as a buffer for libraries like PHP GD, which might use it for copying bytes. 

Here are details from my web app of processing a 16MP JPEG with GD functions (total 172MB, calculated with memory_get_peak_usage):

  • imagecreatefromjpeg: +68MB
  • imagewebp: 130MB (+62MB)
  • resizeWebP:
    • imagecreatefromwebp: 140MB (+10MB)
    • imagecreatetruecolor: 156MB (+16MB)
    • imagewebp: 172MB (+16MB)

To be safe, allocating 200MB of memory would be prudent. If your server has 3GB total RAM, it means that your web app can handle at most 3GB/200MB ≈ 15 concurrent image conversions.

Converting images to WebP saves disk space and speeds up the web app in the long run, but it consumes a lot of RAM in the short run.

Monday, December 23, 2024

Why Software Project Estimation Is Difficult

In my experience, there are three factors that make software project effort/cost estimation difficult:

  1. It is much easier to estimate for the happy path which leaves gaps in specifications for handling edge cases and exceptions.
  2. Not cleaning up code during development.
  3. Frequent changes in libraries and frameworks necessitating unplanned rework.

Handling error cases and edge conditions often takes much more effort than the happy path due to the need for additional logic, testing, and debugging. If edge cases are not considered early, addressing them later can introduce costly redesign efforts. Unfortunately, the number and complexity of edge cases grow as the project progresses, especially if new scenarios are discovered during development or testing. Handling one error case might introduce or expose others, creating a chain of additional considerations that were not part of the original estimate.

Neglecting regular code cleanup leads to the accumulation of technical debt, which increases the time and effort required to implement similar features later in the project. New developers joining the team may struggle to understand and contribute to the codebase, further slowing development. Additionally, the effort required to fix bugs, integrate new systems, or perform upgrades can grow exponentially over time.

APIs, libraries and frameworks are typically updated every six months, and programming languages undergo significant changes every few years. While these updates bring improvements, they can impact project timelines.

All these factors can make your initial effort/time estimation 10 times less than the actual cost in the end. A rule of thumb you can use is to estimate for the happy path and multiply that by 10 to get a realistic number.

Monday, December 2, 2024

Interpreted vs compiled programming languages

With an interpreted language like Python or PHP, if you notice a bug in the web app API logic or the UI script, you can fix it and test the change immediately. This is much faster than stopping to recompile and deploy every time, as would be required in a compiled language.

Without compiled binaries, the same source code can be deployed on multiple platforms without adjustments, as long as the runtime environment is consistent.

Many modern web frameworks (e.g., Flask, Laravel Vite) have features like "hot reloading," which automatically detect changes in code and reload the application without restarting. This is much easier to implement in interpreted environments.

While these advantages are significant, they may come at the cost of runtime performance and error detection, as compilation often catches errors early. However, for most web applications, the increased development speed and flexibility usually outweigh these trade-offs.

Music: The Cardigans - My Favorite Game

Friday, November 29, 2024

Base64 encoding

Base64 encoding ensures that the output only contains characters from a specific, limited set of 64 characters, which are: ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/

It is safe for most text-based systems because none of the potentially problematic characters (\, \0, \n, \r, \x1a, ', ") appear in the output. Note that \x1a is the hexadecimal representation of the ASCII control character SUB (substitute). It is a non-printable character with the decimal value 26 in the ASCII table. If included in a text string, \x1a is typically invisible and may disrupt processing, especially in legacy systems that interpret it as EOF.

Example:

<?php
/**
* @throws RandomException
*/
public static function createToken($customer_id, $email): string {
$data = json_encode(['customer_id' => $customer_id, 'email' => $email, 'nonce' => bin2hex(random_bytes(16))]); // Add random characters to minimize collision risk
return base64_encode($data);
}
public static function extractEmail($email_verification_token): string {
$data = base64_decode($email_verification_token);
$decoded = json_decode($data, true);
return $decoded['email'];
}
view raw base64Token.php hosted with ❤ by GitHub

Base64 encoding increases the size of the input data by approximately 33%. Specifically: For every 3 bytes of input, base64 adds 4 characters. For example if input JSON is {"customer_id":123,"email":"user@example.com","nonce":"d1a2b3c4d5e6f7g8h9i0j1k2l3m4n5o6"}, which is 94 characters, the output will be eyJjdXN0b21lcl9pZCI6IDEyMywgImVtYWlsIjogInVzZXJAZXhhbXBsZS5jb20iLCAibm9uY2UiOiAiZjVkMGMzZGY3ZTM3ODQ2NWQ0NjhkMTdjZTRhNGNlMzIifQ==, which is 128 characters. Note the "==" characters at the end. These are used for padding which ensures the length of the encoded string is a multiple of 4. If your database column to hold the token is VARCHAR(255), assuming a max customer_id of "999 999 999", max email size should not exceed 111 characters.

Email max lengths [RFC 5321, Simple Mail Transfer Protocol]:

  • Local part (before the @): Up to 64 characters (octet = byte).
  • Domain part (after the @): Up to 255 characters.

Total length: The maximum length of a valid email address is 320 characters, but this is extremely rare in practice.

Music: Barış Manço - Dönence

Thursday, November 28, 2024

Concept of Operations

Writing a Concept of Operations (CONOPS) is the first and most important step in a project and should ideally be prepared before a contract is signed. The CONOPS provides a shared understanding of the project's goals, scope, and operational context. This clarity is essential for creating a contract that accurately reflects stakeholder expectations. It bridges the gap between stakeholders' needs and the technical execution. It includes example workflows of at least the happy paths to demonstrate how the system will function. These workflows should clearly specify who is doing what; in other words, there should be no sentences written in the passive voice. Example workflow for email verification on new customer registration:
1. The customer clicks the "Register" button on the registration form.
2. The browser sends a registration request to the server.
3. The server generates a customer email verification token.
4. The server saves the token to the email_verification_token field in the database.
5. The server sends an email to the customer containing the verification link with the token.
6. The server responds with the page: “Registration successful. We have sent you an email. Open that email and click on the verification link to complete the registration.”
7. The browser displays the "Registration successful" page to the customer.
8. The customer opens the email and clicks the verification link.
9. The browser sends a verification request to the server.
10. The server retrieves the customer from the database using the token included in the request.
   a. If the token cannot be found, the server responds with the login page.
11. The server sets the customer's email_verification_token field to NULL.
12. The server responds with the page: “Registration complete. Link: Login”
13. The browser displays the page to the customer.
14. The customer clicks the login link.
15. The browser sends a login request to the server.
16. The server retrieves the customer's data for the login email.
17. The server verifies the password. If the password is correct, the server checks the email_verification_token field. 
18. If the token is NULL, the server logs in the user and responds with the customer dashboard page.
    a. The browser displays the dashboard to the customer.
19. If the token is not NULL, the server responds with the page: “To continue with the login, click on the verification link in the email we have sent you. Link: Send verification email again.”

Sunday, November 17, 2024

Data Transfer Objects

Data Transfer Objects (DTOs) decouple the internal structure of your models, entities, or database schema from the data exposed to the external world (e.g., APIs, front-end). They serve as a contract for the data being transferred, which helps ensure that changes in your data layer don't inadvertently affect the consumer.

Another benefit of DTOs is to enforce structured data and eliminate errors from missing [string] keys. By using a constructor, you control how the raw data is mapped. If a key is missing, you can provide a default value or handle the absence gracefully or you can add validation logic centrally in constructor. Using DTOs allows tools like PhpStorm or VSCode to identify missing properties during development. When working with arrays, typos in keys can go unnoticed until runtime, with DTOs you are using object fields which don’t have this weakness. Example without DTO (note the usage of error prone string keys):

private function prepareProductDetails(array $product): array {
        $product['photos'] = $this->processProductPhotos($product['photos']??[]);
        $product['tr_currency_formatted'] = isset($product['deposit']) 
                ?Currency::formatTRY($product['deposit'])
        return $product;
    }

With DTO:

class ProductDetailsDTO {
    public array $photos;
    public ?float $deposit = null;
    public ?string $tr_currency_formatted = null;
    public function __construct(array $data) {
        $this->photos = $data['photos'] ?? [];
        $this->deposit = $data['deposit'] ?? null;
    }
    public function setFormattedCurrency(callable $formatter): void {
        if ($this->deposit !== null) {
            $this->tr_currency_formatted = $formatter($this->deposit);
        }
    }
}

Note the usage of object fields instead of string keys:

private function prepareProductDetails(array $product): ProductDetailsDTO {
    $productDTO = new ProductDetailsDTO($product);
    $productDTO->photos = $this->processProductPhotos($productDTO->photos);
    $productDTO->setFormattedCurrency(fn($amount) =>
        Currency::formatTRY($amount));
    return $productDTO;
}