DEV Community: Rubem Vasconcelos

Building Authentication Without Collecting Any Personal Data

Rubem Vasconcelos — Thu, 26 Mar 2026 02:07:30 +0000

What If Your Auth System Collected Zero Personal Data?

Traditional authentication has a common pattern: it requires you to collect personal information before you can verify identity. Email. Phone number. Password. All of it ends up in a database, and databases get breached.

But there's a different model — one borrowed from cryptocurrency wallets — where the server stores nothing that can be traced back to a real person. Let's build it.

The Core Idea

Instead of email + password, the user gets a 12-word seed phrase. From that phrase, we derive a cryptographic key pair. The public key becomes their anonymous identity on the server. The private key and the raw mnemonic never leave the browser.

Login doesn't ask for the full phrase either. It challenges the user to provide 3 randomly chosen words — which are hashed client-side before comparison. The server only ever sees hashes.

Here's what the server ends up storing:

{
  "username": "a1b2c3d4",
  "publicKey": "8f7a9b2c1d3e4f5a...",
  "mnemonicHashes": [
    "e3b0c44298fc1c14...",
    "d7a8fbb307d78094...",
    "..."
  ]
}

No email. No password. No name. Nothing linkable to a person.

Step 1: Generating the Seed Phrase (BIP-39)

BIP-39 is the standard used by hardware wallets like Ledger and Trezor. It maps 128 bits of random entropy to 12 words from a fixed 2048-word English dictionary. Each word encodes roughly 11 bits of information — enough that the full phrase has ~128 bits of security.

import { generateMnemonic } from '@scure/bip39';
import { wordlist } from '@scure/bip39/wordlists/english.js';

// 128 bits of entropy → 12 words
const mnemonic = generateMnemonic(wordlist, 128);
// "witch collapse practice feed shame open despair creek road again ice least"

The @scure/bip39 library is audited and has zero dependencies — important for anything touching key material.

Step 2: Deriving the Ed25519 Key Pair

Ed25519 is a fast, secure elliptic-curve signature scheme. A 32-byte private key deterministically produces a 32-byte public key. We derive the private key from the mnemonic using HMAC-SHA-256 with a domain-separation tag — this ensures the same mnemonic produces different keys for different applications.

import { mnemonicToSeedSync } from '@scure/bip39';
import * as ed from '@noble/ed25519';
import { hmac } from '@noble/hashes/hmac';
import { sha256 } from '@noble/hashes/sha2';

async function deriveKeyPair(mnemonic: string) {
  // BIP-39: mnemonic → 64-byte seed
  const seed = mnemonicToSeedSync(mnemonic);

  // HMAC with a domain tag — same seed, different keys per app
  const derived = hmac(
    sha256,
    new TextEncoder().encode('your-app-name-ed25519'),
    seed
  );

  const privateKey = derived.slice(0, 32);
  const publicKey = await ed.getPublicKeyAsync(privateKey);

  return {
    publicKey: bytesToHex(publicKey),   // goes to the server
    privateKey: bytesToHex(privateKey), // stays in the browser, forever
  };
}

The domain tag ('your-app-name-ed25519') is what prevents key reuse across different systems using the same BIP-39 seed.

Step 3: Hashing the Mnemonic Words

Before any data leaves the browser, each of the 12 words is hashed individually using SHA-256 via the native Web Crypto API. The server stores these hashes — never the words themselves.

async function hashWord(word: string): Promise<string> {
  const data = new TextEncoder().encode(word.trim().toLowerCase());
  const buffer = await crypto.subtle.digest('SHA-256', data);
  return Array.from(new Uint8Array(buffer))
    .map(b => b.toString(16).padStart(2, '0'))
    .join('');
}

// Hash all 12 words in parallel
const mnemonicHashes = await Promise.all(
  mnemonic.split(' ').map(hashWord)
);

A note on salting: BIP-39 words are common English words, making them vulnerable to precomputed rainbow tables in theory. For production, you'd want to salt each hash with something unique per user (e.g., their public key). This demo keeps it simple for clarity.

Step 4: Registration

The client sends three things to the server — and none of them are personally identifiable:

await register({
  username: someAnonymousId,   // could be anything — a hash, a UUID
  publicKey: keyPair.publicKey,
  mnemonicHashes,
});

That's the entire registration payload. The server has no way to contact this user, no way to identify them in the real world, and nothing useful to hand over in a breach.

Step 5: The Login Challenge

This is the most interesting part. Login doesn't ask for the full mnemonic — it picks 3 random positions and asks the user to type only those words.

// Pick 3 unique random positions from 0–11
function pickRandomIndices(count: number, total: number): number[] {
  const indices = new Set<number>();
  while (indices.size < count) {
    indices.add(Math.floor(Math.random() * total));
  }
  return [...indices].sort((a, b) => a - b);
}

const challengeIndices = pickRandomIndices(3, 12);
// e.g. [1, 6, 10] → "Enter words #2, #7, and #11"

The user types those 3 words. Each one is hashed client-side, then compared against the stored hash at that position:

const isAuthenticated = await Promise.all(
  challengeIndices.map(async (idx, i) => {
    const hash = await hashWord(userInput[i]);
    return hash === storedHashes[idx];
  })
).then(results => results.every(Boolean));

if (isAuthenticated) {
  saveSession(publicKey);
}

The full mnemonic is never transmitted. The server never sees plaintext words. Only hashes travel over the wire — and only 3 of the 12, at random positions that change every login.

What About Sessions?

Sessions store the minimum possible state: the public key and an expiry timestamp.

interface SessionData {
  publicKey: string;
  expiresAt: number;
}

function saveSession(publicKey: string): void {
  const session: SessionData = {
    publicKey,
    expiresAt: Date.now() + 2 * 24 * 60 * 60 * 1000, // 2 days
  };
  storage.set('session', session);
}

No JWT with an email claim. No cookie with a user ID tied to a real person. Just a public key reference.

The Trade-offs (Honestly)

This architecture makes some things genuinely better and some things genuinely harder.

Better:

A database breach exposes nothing usable — public keys and hashes only
No "forgot password" attack surface exists, because there's no password
No email = no phishing vector tied to this account
The user owns their identity completely

Harder:

Losing the seed phrase means losing the account. Permanently. No recovery.
Users unfamiliar with seed phrases need onboarding. This is real UX work.

The Libraries

Everything cryptographic uses audited, zero-dependency implementations from Paul Miller:

Library	Role
`@scure/bip39`	Mnemonic generation from entropy
`@noble/ed25519`	Key pair derivation and signing
`@noble/hashes`	SHA-256, HMAC for key derivation
Web Crypto API	SHA-256 word hashing (built-in)

Audited libraries matter here. Key derivation code is security-critical and not the place for unreviewed dependencies.

Conclusion

The shift this pattern forces is conceptual more than technical: instead of asking "how do we protect our users' data?", you ask "what if we simply didn't have it?".

The cryptographic primitives — BIP-39, Ed25519, SHA-256 — are battle-tested and well-understood. The challenge is UX: helping users understand that their 12 words are their account, and that means treating them with the same care as a physical key.

For the right use case — privacy tools, pseudonymous platforms, self-sovereign applications — this model removes an entire category of risk from the threat surface.

Full open source demo: GitHub link

From Monoliths to Microservices: Rethinking the Test Pyramid

Rubem Vasconcelos — Thu, 19 Feb 2026 13:13:29 +0000

In the previous article, I explored the fundamentals of software testing and the classic Test Pyramid.

This post builds on that foundation and is adapted from Chapter 4 – Tests in Microservices of my Master’s thesis, where I analyze how testing strategies evolve when moving from monolithic architectures to distributed microservices systems.

The core idea is simple:

The Test Pyramid still applies — but its structure must evolve in distributed systems.

Testing in Monolithic Systems

Monolithic systems are deployed as a single unit. All components share the same codebase, runtime, and memory space.

This architectural simplicity has direct implications for testing.

Image Source: Martin Fowler, The Practical Test Pyramid

It usually includes:

Unit Tests
Integration Tests
End-to-End (or UI) Tests

Unit Tests

Unit testing focuses on validating small, isolated parts of the system. As Fowler (2014) emphasizes, unit tests should be fast and independent, forming the foundation of the test suite.

Because everything runs within the same process, isolation is easier and execution is deterministic.

Integration Testing

Integration testing combines components and verifies their interactions.

According to ISTQB (2018), integration testing aims to expose defects in interfaces and interactions between integrated components or systems.

Two common forms include:

Component integration testing – interaction between internal modules
System integration testing – interaction with external systems (e.g., third-party APIs)

In monolithic systems, integration remains relatively predictable because communication occurs within the same application boundary.

End-to-End Testing

System testing evaluates the fully integrated system against specified requirements (ISTQB, 2018).

End-to-end testing simulates real user flows, validating complete business scenarios across the application stack (Fowler & Lewis, 2014).

Since monoliths are deployed as a single artifact, validation of full flows is operationally simpler than in distributed architectures.

What Changes With Microservices?

Microservices architectures introduce:

Independent deployments
Network communication
Asynchronous messaging
Distributed data management
Cross-team ownership
Runtime unpredictability

Failures no longer occur only inside the codebase — they happen between services, across network boundaries.

Bozkurt, Harman, and Hassoun (2010) observed that distributed systems introduce higher testing complexity due to:

Dynamic service behavior
Simultaneous distributed transactions
Multiple implementations under shared specifications
Cross-team coordination

This complexity forces a structural evolution of the testing strategy.

The Microservices Test Pyramid

Image Source: SOTOMAYOR et al. (2023)

In addition to traditional:

Unit Tests
Integration Tests
End-to-End Tests

Microservices introduce two critical layers:

Component Tests
Contract Tests

In many models, integration, component, and contract tests form the broader service testing layer.

Unit Testing in Microservices

In microservices, units typically include:

Domain services
Resource handlers
Gateways
Repositories

However, as Habl, Kipouridis, and Fottner (2017) note, successful isolated unit tests do not guarantee correct behavior once components interact within distributed systems.

Network boundaries fundamentally change the reliability assumptions.

Integration Testing in Distributed Systems

In microservices, integration testing focuses on:

Database interactions
Inter-service communication
Messaging systems
External APIs

Sotomayor et al. (2023) highlight that integration testing in microservices architectures must explicitly validate communication layers and service coordination mechanisms.

Common failure sources include:

Serialization mismatches
Version incompatibilities
Timeout configurations
Infrastructure inconsistencies

Integration tests must validate these boundaries intentionally.

Component Testing

Component testing treats each microservice as an independent system.

Using:

Mocks
Stubs
Simulated dependencies

external network interactions are removed during testing.

This ensures:

Deterministic execution
Faster feedback loops
Reduced flakiness

As Fowler and Lewis (2014) argue, isolating services during testing is essential to prevent infrastructure instability from compromising test reliability.

Component tests bridge the gap between isolated unit tests and full distributed integration.

Contract Testing: A Structural Necessity

One of the most important additions in microservices architectures is contract testing.

Contract testing verifies service boundaries and interaction agreements.

Sotomayor et al. (2023) define contract testing in microservices as the validation of service boundaries to ensure compatibility between independently evolving services.

In distributed systems:

APIs define request/response contracts
Messaging schemas define event contracts
Consumers depend on explicit interface structures

If a provider changes its contract without coordination, it may break consumers in production.

Contract testing ensures:

Schema compatibility
Behavioral consistency
Safe independent deployments

Contract testing addresses methodological complexity introduced by independently deployed microservices.

Tools like Pact are widely used to operationalize this practice.

Why End-to-End Tests Must Be Minimized

End-to-end testing in microservices:

Requires multiple services running simultaneously
Depends on production-like environments
Is slower and more fragile
Is harder to debug

Over-reliance on E2E tests can lead to:

Flaky CI pipelines
Slow feedback cycles
High maintenance overhead

Cohn (2010) already recommended minimizing top-layer tests in the Test Pyramid. In microservices architectures, this recommendation becomes even more critical.

Confidence should be built lower in the pyramid — especially at service boundaries.

Structural Differences: Monolith vs Microservices

Monolith	Microservices
Failures mostly internal	Failures often at boundaries
Shared memory communication	Network communication
Single deployment	Independent deployments
Implicit contracts	Explicit contracts
Centralized coordination	Distributed coordination

Testing evolves from validating internal correctness to validating communication guarantees and service contracts.

Final Thoughts

Microservices provide:

Scalability
Deployment independence
Team autonomy

But they introduce:

Greater operational complexity
Increased testing surface area
More failure modes

The Test Pyramid still applies — but its center shifts toward:

Strong unit tests
Robust service-level tests
Explicit contract validation
Minimal, strategic end-to-end tests

In distributed systems, testing strategy becomes an architectural decision.

References

Bozkurt, M., Harman, M., & Hassoun, Y. (2010). Testing web services: A survey.
Cohn, M. (2010). Succeeding with Agile: Software Development Using Scrum. Addison-Wesley.
Fowler, M. (2014). The Practical Test Pyramid. martinfowler.com
Habl, G., Kipouridis, I., & Fottner, J. (2017). Deploying microservices for a cloud-based design of system-of-systems in intralogistics. IEEE.
ISTQB (2018). Standard Glossary of Terms Used in Software Testing.
Sotomayor, B. et al. (2023). Comparison of open-source runtime testing tools for microservices. Software Quality Journal, Springer.

This article is adapted from Chapter 4 – “Tests in Microservices” of my Master’s thesis, which presents a comparative analysis of testing strategies in monolithic and microservices-based systems.

Software Testing Fundamentals: Black Box, White Box, and the Test Pyramid

Rubem Vasconcelos — Thu, 29 Jan 2026 19:15:29 +0000

Software testing plays a fundamental role in ensuring that systems behave as expected and meet both user and business requirements. While tools and frameworks evolve quickly, the core testing principles remain largely the same.

The fundamental objective of software testing is to verify whether the system behaves according to previously defined expectations (Bourque & Fairley, Guide to the Software Engineering Body of Knowledge, 2014).

This article is adapted from Chapter 4 – Tests in Microservices of my Master’s thesis, where I analyze software testing strategies and how they scale from traditional systems to modern architectures.

In this post, I’ll focus on the fundamentals of software testing and the Test Pyramid, which serves as the foundation for understanding more advanced testing approaches.

What is the Goal of Software Testing?

At its core, software testing aims to ensure that a system conforms to expected behavior and defined requirements.

Software testing seeks to validate whether a system is in accordance with functional and non-functional requirements previously established.

Beyond simply finding bugs, testing helps reduce risks in production environments and increases confidence when evolving software systems.

Software Testing Techniques

Software testing techniques can be broadly classified into three categories (Mathur, Foundations of Software Testing, 2013):

Black-box testing
White-box testing
Gray-box testing

Each of these techniques plays a complementary role in achieving adequate test coverage.

Black-box Testing

Black-box testing evaluates the functionality of a system without considering knowledge of its internal structure. The tester focuses exclusively on inputs and outputs, without concern for implementation details or internal logic.

In black-box testing, the tester concentrates on analyzing system inputs and outputs, without worrying about the underlying logic or component implementation.

This technique is effective in validating user requirements and detecting failures that may not be evident through internal code analysis.

Advantages:

No need for internal code knowledge
Faster execution and lower cost
Good alignment with user expectations

Limitations:

Cannot detect internal logic or implementation errors
Limited visibility into hidden edge cases

For this reason, black-box testing should always be combined with other testing approaches.

White-box Testing

White-box testing is based on the analysis of the internal structure of the system, requiring detailed knowledge of the source code and component logic.

White-box testing evaluates not only system functionality, but also efficiency, security, and maintainability.

This technique enables the identification of:

Logical flaws
Syntax errors
Execution path issues
Security vulnerabilities

It also supports code optimization, improving performance and scalability.

Challenges:

Higher complexity
Greater time and effort required
Requires strong technical expertise

White-box testing is especially valuable at lower levels, such as unit and component testing.

Gray-box Testing

Gray-box testing combines characteristics of black-box and white-box testing. The tester has limited access to the system’s internal structure, allowing partial analysis of the code and logic.

“Gray-box testing enables the detection of failures that would not be evident through purely external analysis, without the complexity associated with full white-box testing.”

— Mathur, Foundations of Software Testing

This approach offers a good balance between coverage and cost, although limited internal access can still restrict test precision.

Functional vs Non-functional Testing

In addition to testing techniques, defining testing objectives is a fundamental part of the software testing process.

According to Bourque & Fairley, in the Guide to the Software Engineering Body of Knowledge (2014), identifying testing objectives is a fundamental aspect of the software testing process.

These objectives are commonly divided into two categories.

Functional Tests

Functional tests aim to validate system functionalities and verify whether they comply with established requirements. This category often includes end-to-end testing, which validates integration and interaction between different system components.

Non-functional Tests

Non-functional tests focus on system qualities not directly related to functionality, such as:

Performance
Scalability
Reliability
Stress tolerance

Performance and stress tests evaluate system capacity, response time, and behavior under high load and overload conditions (Sotomayor et al., Comparison of runtime testing tools for microservices, 2019).

A clear definition of these objectives helps ensure adequate coverage and minimizes the risk of failures in production environments.

The Test Pyramid

One of the most widely adopted models for organizing software tests is the Test Pyramid, originally proposed by Mike Cohn.

“The 'Test Pyramid' is a metaphor that tells us to group software tests into buckets of different granularity. It also gives an idea of how many tests we should have in each of these groups.”

— Martin Fowler, The Practical Test Pyramid

The pyramid structures tests according to cost, speed, and scope.

Image Source: Martin Fowler, The Practical Test Pyramid

Unit Tests (Base of the Pyramid)

Unit tests focus on small, isolated parts of the system.

According to Martin Fowler in The Practical Test Pyramid, unit tests are expected to be significantly faster than other test categories, and each unit should be tested independently

They are usually written by developers and should represent the majority of the test suite.

Service / Integration Tests (Middle Layer)

Service tests validate integration between components, evaluating services in isolation from the user interface.

Service-level tests fill the gap between unit tests and end-to-end tests. They test the integration of your application with all the parts that live outside of your application (Martin Fowler, The Practical Test Pyramid).

These tests ensure that components collaborate correctly.

End-to-End Tests (Top of the Pyramid)

End-to-end tests validate complete user scenarios by testing the system as a whole.

End-to-end tests aim to simulate interactions with the system in the same way the end user would.

Because they are slower and more fragile, they should be used sparingly.

Recommended Proportions

A commonly recommended distribution is:

More than 60% unit tests
Less than 30% service or integration tests
Less than 10% end-to-end tests

Following this structure helps ensure fast and stable tests, while reserving a small number of tests for validating complete user scenarios.

Why the Test Pyramid Still Matters

Although simple, the Test Pyramid remains an effective guideline for building efficient and scalable test suites.

By combining different types of tests and adjusting their quantity at each level, it is possible to obtain comprehensive and efficient test coverage.

References

Bourque, P., & Fairley, R. (2014). Guide to the Software Engineering Body of Knowledge. IEEE.
Mathur, A. (2013). Foundations of Software Testing. Pearson.
Cohn, M. (2010). Succeeding with Agile: Software Development Using Scrum. Addison-Wesley.
Fowler, M. (2014). The Practical Test Pyramid. martinfowler.com
Sotomayor, B. et al. (2019). Comparison of runtime testing tools for microservices.

Building a Movie App with Clean Architecture Concepts in React Native

Rubem Vasconcelos — Tue, 25 Nov 2025 12:30:46 +0000

I'm a huge movie fan, and I've decided to combine my passion for cinema with my love for building well-architected systems to practice my React Native skills. That's how Premiere Night was born.

I've worked with Clean Architecture before. In fact, I built another React Native project with even more layers and complexity, but it was on an older version of React Native. I wanted to challenge myself to apply these same architectural principles to a modern React Native 0.82 setup with the latest tools - in a more simple way.

But this isn't just a "look at my code" post. I made mistakes, learned valuable lessons, and discovered what actually works (and what's overkill) when building production-ready React Native apps. Whether you're a solo developer or working in a team, I hope my experience helps you make better architectural decisions.

What We're Building

Premiere Night is a movie discovery app that lets users:

Browse popular, top-rated, and upcoming movies
Search movies in real-time with debouncing (500ms)
View detailed movie information
Save favorites to an offline watchlist

Tech Stack:

React Native 0.82 (bare workflow, no Expo)
TypeScript 5.8 with strict mode
Redux Toolkit 2.10 for state management
React Navigation 7.x
AsyncStorage for local persistence
Jest + Testing Library (289 passing tests)

🎬 Try Android Demo | 📱 Try iOS Demo | 💻 View Source

Clean Architecture: Breaking It Down

If you've never worked with Clean Architecture before, don't worry! I'll explain it in a way that actually makes sense (I wish someone had done this for me when I started).

The core idea is simple: separate your app into layers where inner layers don't know about outer layers. Think of it like a building where the foundation doesn't care about the paint color on the walls.

If you want to dive deeper into Clean Architecture, I've written guides on the topic:

Clean Architecture: The Concept Behind the Code - Understanding the core principles

Clean Architecture: Applying with React - Practical implementation with React

This post focuses specifically on React Native implementation, but those articles will give you the foundational knowledge if you're new to these concepts.

┌─────────────────────────────────────────┐
│       PRESENTATION LAYER                │
│  (UI, Screens, Components, Hooks)       │
└──────────────┬──────────────────────────┘
               ↓
┌─────────────────────────────────────────┐
│          DATA LAYER                     │
│  (Repositories, DTOs, Mappers)          │
└────────┬─────────────────────┬──────────┘
         ↓                     ↓
┌──────────────────┐  ┌──────────────────┐
│  DOMAIN LAYER    │  │  INFRA LAYER     │
│  (Entities,      │  │  (API, Redux,    │
│   Interfaces)    │  │   Storage)       │
└──────────────────┘  └──────────────────┘

Layer Responsibilities

Domain Layer (Pure TypeScript):

Defines business entities (Movie, MovieDetails)
Defines repository interfaces (IMovieRepository)
Zero external dependencies
Framework-agnostic

Infrastructure Layer:

HTTP client (TMDb API)
Redux store configuration
State slices (movies, search, watchlist, details)
AsyncStorage integration

Data Layer:

Repository implementations (MovieRepositoryImpl)
DTOs matching API responses
Mappers transforming DTOs to domain entities
Data utilities (image URLs, etc.)

Presentation Layer:

React components and screens
Custom hooks for business logic
Navigation configuration
UI styles and themes

Layer Deep Dive

1. Domain Layer: Pure Business Logic

Purpose: Define what the app does, not how.

export interface Movie {
  id: number;
  title: string;
  overview: string;
  posterPath: string | null;
  releaseDate: string;
  voteAverage: number;
}

export interface IMovieRepository {
  getPopularMovies(params?: MovieListParams): Promise<PaginatedResponse<Movie>>;
  getMovieDetails(params: MovieDetailsParams): Promise<MovieDetails>;
  searchMovies(params: MovieSearchParams): Promise<PaginatedResponse<Movie>>;
}

Key Benefits:

No React, no Redux, no external libraries
Easy to understand business rules
Reusable across platforms (web, mobile)
Perfect for documentation

2. Infrastructure Layer: External Systems

Purpose: Handle communication with external dependencies.

class ApiClient {
  private baseURL: string;
  private apiKey: string;

  async get<T>(endpoint: string, params?: Record<string, any>): Promise<T> {
    const url = this.buildUrl(endpoint, params);
    const response = await fetch(url);

    if (!response.ok) {
      throw new Error(`API Error: ${response.status}`);
    }

    return response.json();
  }
}

export const apiClient = new ApiClient();

Why Redux Toolkit?

Excellent TypeScript support with full type inference
Less boilerplate (no action constants, simplified reducers)
Built-in thunk middleware for async actions
Immer integration for immutable updates

3. Data Layer: Transformation Hub

Purpose: Transform external data to domain models.

import { IMovieRepository } from '@domain/repositories/MovieRepository';
import { apiClient } from '@infra/api/ApiClient';
import { MovieMapper } from '../mappers/MovieMapper';

export class MovieRepositoryImpl implements IMovieRepository {
  async getPopularMovies(
    params?: MovieListParams
  ): Promise<PaginatedResponse<Movie>> {
    // 1. Fetch from API
    const response = await apiClient.get<PaginatedResponseDTO<MovieDTO>>(
      'movie/popular',
      { page: params?.page, language: params?.language || 'en-US' }
    );

    // 2. Transform DTO to Domain
    return MovieMapper.toPaginatedDomain(response, MovieMapper.toDomain);
  }
}

export const movieRepository = new MovieRepositoryImpl();

The Mapper Pattern:

export class MovieMapper {
  static toDomain(dto: MovieDTO): Movie {
    return {
      id: dto.id,
      title: dto.title,
      overview: dto.overview,
      posterPath: dto.poster_path, // snake_case → camelCase
      releaseDate: dto.release_date,
      voteAverage: dto.vote_average,
    };
  }
}

Why Mappers?

API contracts change, domain models don't
Centralized transformation logic
Easy to test in isolation
Type-safe conversions

4. Presentation Layer: User Interface

Custom Hooks Pattern:

import { useAppDispatch, useAppSelector } from '@infra/store/hooks';
import { fetchPopularMovies, selectMoviesState } from '@infra/store/movies';

export const useMovies = () => {
  const dispatch = useAppDispatch();
  const moviesState = useAppSelector(selectMoviesState);

  useEffect(() => {
    dispatch(fetchPopularMovies({ page: 1 }));
  }, [dispatch]);

  const loadMore = useCallback(() => {
    dispatch(fetchPopularMovies({ 
      page: moviesState.popular.currentPage + 1, 
      append: true 
    }));
  }, [dispatch, moviesState.popular.currentPage]);

  return {
    movies: moviesState.popular.data,
    loading: moviesState.popular.loading,
    error: moviesState.popular.error,
    loadMore,
  };
};

Benefits:

Components focus solely on rendering
Business logic is reusable and testable
Easy to mock in tests
Hooks can be tested independently of UI

Implementing a Feature: Movie Search

Let's implement the search feature step-by-step to see the architecture in action.

Step 1: Define Domain Contract

export interface MovieSearchParams {
  query: string;
  page?: number;
  language?: string;
  year?: number;
}

export interface IMovieRepository {
  searchMovies(params: MovieSearchParams): Promise<PaginatedResponse<Movie>>;
}

Step 2: Implement Repository

async searchMovies(
  params: MovieSearchParams
): Promise<PaginatedResponse<Movie>> {
  const response = await apiClient.get<PaginatedResponseDTO<MovieDTO>>(
    'search/movie',
    {
      query: params.query,
      page: params.page,
      language: params.language || 'en-US',
      year: params.year,
    }
  );

  return MovieMapper.toPaginatedDomain(response, MovieMapper.toDomain);
}

Step 3: Create Redux Slice

const searchSlice = createSlice({
  name: 'search',
  initialState: {
    query: '',
    results: [],
    loading: false,
    hasSearched: false,
  },
  reducers: {
    setSearchQuery: (state, action: PayloadAction<string>) => {
      state.query = action.payload;
    },
    clearSearch: (state) => {
      state.query = '';
      state.results = [];
      state.hasSearched = false;
    },
  },
  extraReducers: (builder) => {
    builder
      .addCase(searchMovies.pending, (state) => {
        state.loading = true;
      })
      .addCase(searchMovies.fulfilled, (state, action) => {
        state.loading = false;
        state.results = action.payload.results;
        state.hasSearched = true;
      });
  },
});

Step 4: Create Custom Hook with Debounce

This is where the magic happens - debouncing reduces API calls by ~80%.

export const useMovieSearch = (debounceTime = 500) => {
  const dispatch = useAppDispatch();
  const searchState = useAppSelector(selectSearchState);
  const [localQuery, setLocalQuery] = useState('');
  const debounceTimer = useRef<ReturnType<typeof setTimeout> | null>(null);

  const handleQueryChange = useCallback((query: string) => {
    setLocalQuery(query); // Immediate UI update
    dispatch(setSearchQuery(query));

    if (debounceTimer.current) {
      clearTimeout(debounceTimer.current);
    }

    if (query.trim().length === 0) {
      dispatch(clearSearch());
      return;
    }

    // Debounced API call
    if (query.trim().length >= 2) {
      debounceTimer.current = setTimeout(() => {
        dispatch(searchMovies({ query: query.trim(), page: 1 }));
      }, debounceTime);
    }
  }, [dispatch, debounceTime]);

  useEffect(() => {
    return () => {
      if (debounceTimer.current) {
        clearTimeout(debounceTimer.current);
      }
    };
  }, []);

  return {
    query: localQuery,
    results: searchState.results,
    loading: searchState.loading,
    onQueryChange: handleQueryChange,
  };
};

Why Debounce?

Reduces API calls by ~80% during typing
Better performance and UX
Respects TMDb API rate limits
Immediate visual feedback, delayed API call

Step 5: Use in Component

export const HomeScreen = () => {
  const { query, results, loading, onQueryChange } = useMovieSearch();

  return (
    <View>
      <SearchBar 
        value={query}
        onChangeText={onQueryChange}
        placeholder="Search movies..."
      />
      {loading && <ActivityIndicator />}
      {results.length > 0 && <SearchResults movies={results} />}
    </View>
  );
};

Why This Architecture Changed My Life (Okay, My Codebase)

Let me be honest, when I started, I thought "this is way too much work". But after finishing the project, I can clearly see the benefits. Here's what I gained:

1. Testing Became More Enjoyable

Each layer can be tested independently, which means:

No more "change one thing, break everything" moments
Tests run faster because you're not booting up the whole app
99.77% coverage wasn't painful—it was achievable!

// Test mapper without API
describe('MovieMapper', () => {
  it('should map DTO to domain', () => {
    const dto: MovieDTO = {
      id: 1,
      title: 'Test Movie',
      poster_path: '/test.jpg',
    };

    const result = MovieMapper.toDomain(dto);

    expect(result).toEqual({
      id: 1,
      title: 'Test Movie',
      posterPath: '/test.jpg',
    });
  });
});

// Test repository with mocked API
jest.mock('@infra/api/ApiClient');

describe('MovieRepositoryImpl', () => {
  it('should fetch popular movies', async () => {
    const mockResponse = { results: [/* ... */] };
    (apiClient.get as jest.Mock).mockResolvedValue(mockResponse);

    const result = await movieRepository.getPopularMovies();

    expect(apiClient.get).toHaveBeenCalledWith('movie/popular', expect.any(Object));
    expect(result.results).toHaveLength(mockResponse.results.length);
  });
});

// Test hook without rendering UI
const { result } = renderHook(() => useMovieSearch(), {
  wrapper: ({ children }) => <Provider store={store}>{children}</Provider>,
});

act(() => {
  result.current.onQueryChange('Avatar');
});

await waitFor(() => {
  expect(result.current.loading).toBe(false);
});

Test Distribution:

Unit tests: ~180 (Mappers, utils, reducers)
Integration tests: ~60 (Redux slices with thunks)
Component tests: ~49 (React components and hooks)

2. Maintainability

Clear boundaries: Each layer has a single responsibility
Easy to find code: Predictable folder structure
Type-safe refactoring: TypeScript catches breaking changes
Self-documenting: Interfaces serve as documentation

3. Flexibility

Want to switch from Redux to Zustand?

Only change the Infra layer
Domain and Data layers stay the same
Components use the same custom hooks

Want to add GraphQL?

Create new repository implementation
Keep domain entities unchanged
Swap implementations via dependency injection

4. Scalability

Adding new features is straightforward:

Define domain contract
Implement repository
Create Redux slice (if needed)
Build UI components

Each step is independent and testable.

Let's Talk About The Elephant in The Room

Is this overkill? Sometimes, yes. Let me be brutally honest about the downsides:

1. You'll Create A LOT of Files

Real talk:

I spent 30% more time on setup than a simpler approach
For every feature, I created DTOs, Mappers, Interfaces, Tests...

But, in my opinion, here's when it's worth it:

Medium to large projects
Team of 2+ developers
Long-term maintenance expected
High test coverage required

When It's Overkill:

Quick prototypes
Simple CRUD apps
Solo weekend projects

2. Learning Curve

Team members need to understand:

Layer boundaries and dependencies
Repository pattern
DTO vs Domain entities
When to create new abstractions

Solution:

Good documentation (like ARCHITECTURE.md)
Code reviews to enforce patterns
Pair programming for onboarding

3. Initial Overhead

First feature takes longer:

Set up folder structure
Configure TypeScript path aliases
Create base interfaces
Set up testing infrastructure

But subsequent features are faster:

Copy-paste and adapt existing patterns
Reuse mappers, utilities, components
Clear guidelines reduce decision fatigue

Key Concepts Explained

Repository Pattern

What: Interface that abstracts data access logic.

Why:

Decouple business logic from data source
Easy to mock in tests
Can swap implementations (REST → GraphQL)

Example:

// Domain defines what we need
interface IMovieRepository {
  getPopularMovies(): Promise<Movie[]>;
}

// Data implements how we get it
class MovieRepositoryImpl implements IMovieRepository {
  async getPopularMovies(): Promise<Movie[]> {
    const response = await apiClient.get('movie/popular');
    return response.results.map(MovieMapper.toDomain);
  }
}

// Tests can use a fake implementation
class FakeMovieRepository implements IMovieRepository {
  async getPopularMovies(): Promise<Movie[]> {
    return [{ id: 1, title: 'Test Movie', /* ... */ }];
  }
}

DTO (Data Transfer Object)

What: Object that matches external API shape.

Why:

API uses snake_case, we use camelCase
API might change, our domain shouldn't
Separates external contract from internal model

Example:

// DTO: Matches API response
interface MovieDTO {
  id: number;
  title: string;
  poster_path: string | null; // snake_case from API
  vote_average: number;
}

// Domain: Our internal model
interface Movie {
  id: number;
  title: string;
  posterPath: string | null; // camelCase for TypeScript
  voteAverage: number;
}

// Mapper bridges the gap
MovieMapper.toDomain(dto);

Redux Slice Pattern

What: Co-locate all Redux logic for a feature in one place.

Structure:

store/movies/
├── slice.ts       # Reducers
├── thunks.ts      # Async actions
├── selectors.ts   # State queries
├── initialState.ts
└── tests/

Benefits:

All related code in one place
Easy to find and modify
Clear feature boundaries
Simple to test

Custom Hooks for Business Logic

What: Extract component logic into reusable hooks.

Why:

Components focus on rendering
Logic is reusable across components
Easy to test without mounting components
Better separation of concerns

Example:

// Hook handles business logic
const useMovies = () => {
  const dispatch = useAppDispatch();
  const movies = useAppSelector(selectPopularMovies);

  useEffect(() => {
    dispatch(fetchPopularMovies());
  }, []);

  return { movies };
};

// Component just renders
const MovieList = () => {
  const { movies } = useMovies();
  return <FlatList data={movies} />;
};

Results: By The Numbers

99.77% Statement Coverage
98.41% Branch Coverage
100% Function Coverage
289 Passing Tests
4 Clear Layers
0 Circular Dependencies

Questions You Might Be Asking

Q: "Is this overkill for my 5-screen app?"

A: Yes, probably. For small projects (< 10 screens), consider:

Simple folder structure (components, screens, utils)
React Query instead of Redux
Fewer abstractions

Use Clean Architecture when:

Team size > 2
Expected lifetime > 6 months
Complexity will grow
High test coverage required

Q: "Does this work with Expo?"

A: Absolutely! I used bare React Native, but the architecture doesn't care. Just:

Swap @react-native-async-storage with expo-secure-store if you want
Use Expo modules wherever you need them
Keep the same layer structure

The beauty of Clean Architecture is that it's framework-agnostic!

Q: "How do you manage API keys securely?"

A: I use react-native-dotenv:

import { TMDB_API_KEY, TMDB_BASE_URL } from '@env';

const apiClient = new ApiClient({
  baseURL: TMDB_BASE_URL,
  apiKey: TMDB_API_KEY,
});

When to Use This Architecture

Great For:

Production apps
Team projects
Apps with complex business logic
High test coverage requirements
Long-term maintenance
Multiple data sources

Overkill For:

Quick prototypes
Solo weekend projects
Simple CRUD apps
Learning projects
MVPs that might be thrown away

Conclusion

Building this app showed me that Clean Architecture isn’t about achieving perfection — it’s about making deliberate, well-reasoned trade-offs. What initially felt overwhelming gradually revealed its value. The test suite reached 99.77% coverage and, instead of feeling unattainable, it became a natural part of the workflow. Adding new features turned into a predictable, almost effortless process once the foundation was in place. Most importantly, refactoring stopped being risky—the architecture and tests consistently supported every change.

Resources

Premiere Night Project:

Learn More About Clean Architecture:

Clean Architecture: The Concept Behind the Code - Core principles and theory
Clean Architecture: Applying with React - Practical React implementation

PixiJS: Implementing Core Gaming Concepts

Rubem Vasconcelos — Mon, 18 Aug 2025 01:02:59 +0000

As a software engineer stepping into game development for the first time (with only some exposure to graphics programming during my bachelor’s degree using Java and OpenGL), I recently began exploring PixiJS to explore fundamental gaming concepts. In this article, I’ll walk through the implementation of three interactive systems that demonstrate sprite management, custom text rendering, and particle effects optimization.

Live Demo | GitHub Repository

What is PixiJS?

PixiJS is a JavaScript library that helps you create interactive 2D graphics in web browsers. If you've worked with HTML Canvas or D3.js for data visualization, think of PixiJS as a more powerful, performance-focused alternative.

The Performance Story: CPU vs GPU

Traditional web graphics (HTML Canvas, SVG) use your computer's CPU to draw everything. This works fine for simple graphics, but becomes slow with complex animations or many visual elements.

PixiJS uses your computer's GPU (Graphics Processing Unit) instead. The GPU is designed specifically for graphics operations and can handle thousands of calculations simultaneously. This is why video games and video editing software are so smooth - they leverage GPU power.

In practical terms: Where Canvas might struggle with 100 moving elements, PixiJS can smoothly handle 1000+ elements at 60fps.

What's a "Sprite"?

In traditional web development, you think in terms of DOM elements (<div>, <img>, <p>). In PixiJS, everything visual is called a "sprite".

Think of a sprite as a lightweight visual object, like a DOM element, but optimized for graphics:

// Instead of: <img src="player.png" style="left: 100px; top: 200px;">
// You have:
const playerSprite = PIXI.Sprite.from('player.png');
playerSprite.x = 100;
playerSprite.y = 200;

Types of sprites you'll work with:

Image sprites: Pictures (like <img> tags)
Text sprites: Rendered text (like <p> or <span>)
Graphics sprites: Drawn shapes (like CSS borders or SVG shapes)
Container sprites: Groups of other sprites (like <div> containers)

The Display Tree for Graphics

Just like HTML has a DOM tree structure, PixiJS has a display tree:

// HTML equivalent:
// <body>
//   <div class="game-container">
//     <img src="player.png">
//     <p>Score: 100</p>
//   </div>
// </body>

// PixiJS equivalent:
const app = new PIXI.Application();           // Like <body>
const gameContainer = new PIXI.Container();   // Like <div>
const playerSprite = PIXI.Sprite.from('player.png'); // Like <img>
const scoreText = new PIXI.Text('Score: 100');       // Like <p>

app.stage.addChild(gameContainer);
gameContainer.addChild(playerSprite);
gameContainer.addChild(scoreText);

Key advantage: Moving the container moves everything inside it, just like CSS transforms on parent elements.

Why Choose PixiJS nowadays?

Performance first: PixiJS automatically uses WebGL when available, providing hardware-accelerated rendering that can handle thousands of sprites at 60fps.
Developer experience: The API is designed to be intuitive and well-documented. Coming from web development, the learning curve is gentle because you're working with familiar concepts like containers, event listeners, and asset loading.
Ecosystem and tooling:
- TypeScript support: First-class TypeScript definitions
- Asset pipeline: Built-in asset loader with support for atlases, fonts, and various image formats
- Plugin system: Extensive plugin ecosystem for filters, particles, and advanced features
- Framework agnostic: Works with React, Vue, Angular, or vanilla JavaScript
Cross-platform ready: PixiJS applications run anywhere modern browsers do, and no additional compilation or platform-specific code is required.
Mobile optimized: Built-in support for high-DPI displays, touch events, and mobile-specific optimizations make it production-ready for mobile games and applications.

Project Architecture Overview

Play Central demonstrates practical applications of PixiJS through three focused implementations:

Ace of Shadows - Automated card dealing system with 144 sprites
Magic Words - Visual novel-style dialogue system with custom emoji support
Phoenix Flame - Performance-constrained particle fire effect

Each system addresses different aspects of game development while maintaining consistent architectural principles throughout the codebase.

Project Structure

src/
├── scenes/
│   ├── BaseScene.ts
│   └── game/
│       ├── ace-of-shadows/
│       │   ├── AceOfShadowsScene.ts
│       │   ├── Card.ts
│       │   └── Deck.ts
│       ├── magic-words/
│       │   ├── MagicWordsScene.ts
│       │   ├── DialogueBox.ts
│       │   ├── AvatarBox.ts
│       │   ├── ResourceManager.ts
│       │   └── types.ts
│       └── phoenix-flame/
│           ├── PhoenixFlameScene.ts
│           └── Particle.ts
├── core/
├── infra/
└── ui/

Implementation 1: Ace of Shadows - Automated Card Dealing System

Objective: Create 144 sprites stacked like cards with automated movement between piles at 1-second intervals, with 2-second animation duration.

Scene Architecture and Separation of Concerns

The AceOfShadowsScene implements clean separation using a dedicated Deck class:

export class AceOfShadowsScene extends BaseScene {
  private deck: Deck;
  private background: PIXI.Sprite;
  private discardPile: PIXI.Container;
  private dealInterval: NodeJS.Timeout | null = null;

  constructor(game: any) {
    super(game, 'Ace of Shadows');
    this.background = PIXI.Sprite.from(BACKGROUND_IMAGE);
    this.addChildAt(this.background, 0);

    this.deck = new Deck(this.game.getApp().renderer);
    this.discardPile = new PIXI.Container();
    this.addChild(this.deck.container, this.discardPile);

    this.startDealing();
  }
}

Key Design Decisions:

Delegation pattern: Card logic encapsulated in Deck class rather than scene management
Automatic termination: Interval stops when deck is empty, preventing unnecessary processing
Clean resource management: Proper interval cleanup in the destroy method

Performance-First Texture Management

The most crucial lesson was understanding sprite vs graphics performance. Instead of 144 individual graphics objects, I generated one reusable texture:

private createCardTexture(): PIXI.Texture {
  const graphics = new PIXI.Graphics();
  graphics.beginFill(0xffffff);
  graphics.lineStyle(2, 0x000000, 1);
  graphics.drawRoundedRect(0, 0, CARD_WIDTH, CARD_HEIGHT, 10);
  graphics.endFill();
  return this.renderer.generateTexture(graphics);
}

private createDeck(): void {
  const cardTexture = this.createCardTexture();
  for (let i = 0; i < NUM_CARDS; i++) {
    const card = new Card(cardTexture);
    card.y = i * STAGGER_OFFSET; // Visual stacking effect
    this.cards.push(card);
    this.container.addChild(card);
  }
}

Timer-Based Animation System with GSAP

The implementation uses interval-based timing with GSAP (a powerful JavaScript library used for creating high-performance animations on the web) for smooth 2-second animations:

private startDealing(): void {
  this.dealInterval = setInterval(() => {
    if (!this.deck.hasCards) {
      if (this.dealInterval) clearInterval(this.dealInterval);
      return;
    }
    this.deck.moveTopCard(this.discardPile);
  }, 1000); // 1-second intervals
}

public moveTopCard(discardContainer: PIXI.Container): void {
  if (this.cards.length === 0) return;

  const card = this.cards.pop()!;
  const worldPos = discardContainer.toGlobal(new PIXI.Point());
  const localPos = card.parent.toLocal(worldPos);

  gsap.to(card.position, {
    x: localPos.x,
    y: localPos.y + (this.discardPile.length - 1) * STAGGER_OFFSET,
    duration: 2, // 2-second animation requirement
    onComplete: () => {
      discardContainer.addChild(card);
    },
  });
}

Implementation 2: Magic Words - Visual Novel Dialogue System

Objective: Create a system combining text and images for RPG-style dialogue using external API data with custom emoji support.

Asynchronous Resource Loading Architecture

The MagicWordsScene implements a loading coordination:

private async loadGameData(): Promise<void> {
  try {
    const [data] = await Promise.all([
      fetchMagicWordsData(),
      PIXI.Assets.load(BACKGROUND_IMAGE),
    ]);

    this.data = data;
    const resourceManager = new ResourceManager(this.data);
    const { emojiTextures, avatarSprites } = 
      await resourceManager.loadAssets();

    this.emojiTextures = emojiTextures;
    this.avatarSprites = avatarSprites;

    Object.values(this.avatarSprites).forEach((sprite) =>
      this.addChild(sprite),
    );

    this.initializeScene();
  } catch (error) {
    console.error('Failed to load game data:', error);
  }
}

Architecture Highlights:

Parallel loading: Background and API data load simultaneously using Promise.all
Resource manager pattern: Dedicated class handles emoji and avatar asset loading
Error handling: Proper try-catch with error reporting

Rich Text Parsing with Inline Emojis

The most complex challenge was parsing text with emoji placeholders like {smile} and rendering them inline. Imagine you need to display text like "Hello {smile} welcome to our game {fire}" where {smile} and {fire} should be replaced with actual emoji images, not text.

In HTML, you might use something like:

<p>Hello <img src="smile.png"> welcome to our game <img src="fire.png"></p>

Unlike HTML, PixiJS doesn’t provide markup-based layout. All elements must be positioned manually. To solve this, we used regex to split the text, identify each part’s type, and then applied custom layout logic to position them individually.

private updateContent(
  text: string,
  emojiTextures: Record<string, PIXI.Texture>,
  wordWrapWidth: number,
): void {
  this.contentContainer.removeChildren();
  let currentX = 0;
  let currentY = 0;
  const FONT_SIZE = 20;
  const LINE_HEIGHT = FONT_SIZE * 1.4;
  const EMOJI_SIZE = FONT_SIZE * 1.2;
  const SPACE_WIDTH = 5;

  const parts = text.split(/(\{[^}]+\})/g).filter((p) => p.length > 0);

  parts.forEach((part) => {
    const emojiMatch = part.match(/\{([^}]+)\}/);
    if (emojiMatch && emojiTextures[emojiMatch[1]]) {
      const emojiName = emojiMatch[1];
      if (currentX + EMOJI_SIZE > wordWrapWidth) {
        currentX = 0;
        currentY += LINE_HEIGHT;
      }
      const emojiSprite = new PIXI.Sprite(emojiTextures[emojiName]);
      emojiSprite.width = EMOJI_SIZE;
      emojiSprite.height = EMOJI_SIZE;
      emojiSprite.y = currentY + (LINE_HEIGHT - EMOJI_SIZE) / 2;
      emojiSprite.x = currentX;
      this.contentContainer.addChild(emojiSprite);
      currentX += emojiSprite.width + SPACE_WIDTH;
    } else {
      // Handle text with word wrapping
      const words = part.split(' ');
      words.forEach((word) => {
        if (word.length === 0) return;
        const textObject = new PIXI.Text(word, {
          fontSize: FONT_SIZE,
          fill: TEXT_COLOR,
        });
        if (currentX + textObject.width > wordWrapWidth) {
          currentX = 0;
          currentY += LINE_HEIGHT;
        }
        textObject.position.set(
          currentX,
          currentY + (LINE_HEIGHT - textObject.height) / 2,
        );
        this.contentContainer.addChild(textObject);
        currentX += textObject.width + SPACE_WIDTH;
      });
    }
  });
}

Implementation 3: Phoenix Flame - Performance-Optimized Particle System

Objective: Create a fire effect within a strict 10-sprite performance constraint.

What's a "Particle" in Graphics Programming?

Imagine you want to create a campfire effect. In real life, fire is made of thousands of tiny flames, sparks, and embers, each moving independently.

In graphics programming, we simulate this with particles, small sprites that:

Spawn continuously (like sparks from a fire)
Move with physics (rise up, drift sideways)
Change over time (fade out, shrink, change color)
Die and get recycled (disappear when their "life" expires)

// Each particle is just a sprite with extra properties
class Particle extends PIXI.Sprite {
  vx: number;    // Horizontal velocity
  vy: number;    // Vertical velocity  
  life: number;  // How long it lives
}

The most challenging thing was creating a realistic fire limited to just 10 sprites maximum. But, with object pooling, we could reuse the same 10 sprites over and over, making them "die" and "respawn" so quickly that it looks like continuous fire.

Object Pooling Pattern Implementation

Instead of creating and destroying particles constantly (that is expensive), we create 10 particles once and reuse them:

export class PhoenixFlameScene extends BaseScene {
  private particles: Particle[] = [];
  private particleContainer: PIXI.ParticleContainer;
  private flameTextures: PIXI.Texture[] = [];

  constructor(game: any) {
    super(game, 'Phoenix Flame');

    this.particleContainer = new PIXI.ParticleContainer(10, {
      scale: true,
      position: true,
      alpha: true,
    });
    this.addChild(this.particleContainer);
  }

  private emitParticle(): void {
    const particle = this.particles.find((p) => !p.visible);
    if (!particle) return; // Pool exhausted

    // Reset particle properties
    particle.position.copyFrom(this.emitter);
    particle.texture = this.flameTextures[this.flameIndex];
    this.flameIndex = (this.flameIndex + 1) % this.flameTextures.length;

    particle.alpha = 1;
    particle.scale.set(0.2 + Math.random() * 0.3);
    particle.visible = true;

    // Set physics properties
    particle.vx = Math.random() * 2 - 1;
    particle.vy = -Math.random() * 3 - 2;
    particle.life = Math.random() * 40 + 50;
  }
}

Physics Simulation and Lifecycle Management

private update(delta: number): void {
  this.emitParticle();

  this.particles.forEach((particle: Particle) => {
    if (!particle.visible) return;

    // Apply velocity and gravity
    particle.x += particle.vx * delta;
    particle.y += particle.vy * delta;
    particle.vy -= 0.05 * delta; // Gravity effect

    // Age the particle
    particle.life -= delta;
    particle.alpha = Math.max(0, particle.life / 60);
    particle.scale.set(particle.scale.x * 0.99); // Shrink over time

    if (particle.life <= 0) {
      particle.visible = false; // Return to pool
    }
  });
}

Conclusion

These implementations demonstrate practical application of core PixiJS concepts through real-world constraints and requirements. The Ace of Shadows system showcases efficient sprite management and timer-based animations, Magic Words illustrates complex resource loading and dynamic UI composition, while Phoenix Flame demonstrates performance optimization through object pooling.

The clean separation of concerns, proper TypeScript integration, and performance-conscious design patterns provide a solid foundation for more complex interactive applications. Each system addresses different aspects of game development while maintaining consistent architectural principles throughout the codebase.

PixiJS proved to be an excellent choice for learning game development concepts, offering the perfect balance of power and simplicity. The modular approach and emphasis on resource management create maintainable, scalable solutions that effectively demonstrate PixiJS capabilities for production-quality interactive applications.

In game development, performance isn’t something to optimize later; it has to be a priority from the start. Unlike traditional web development, where techniques like lazy loading or bundle splitting can be introduced later, games demand smoothness and consistency at every frame. That means carefully managing memory to avoid garbage collection spikes, reusing textures and sprites whenever possible, and relying on specialized structures such as object pooling or optimized containers like ParticleContainer. These aren’t optional enhancements, they’re essential practices for ensuring a stable frame rate and delivering a responsive, enjoyable player experience.

Whether you're building a simple card game, a visual novel, or an action-packed adventure, these patterns and techniques provide a strong foundation for bringing your ideas to life in the browser.

Resources

PixiJS Official Documentation
GSAP Animation Library
Game Programming Patterns - Object pooling and other essential patterns
TypeScript Handbook - For better PixiJS integration

Configure Aplicações React Usando Arquitetura Limpa com Apenas Um Comando

Rubem Vasconcelos — Sun, 31 Jul 2022 15:36:23 +0000

Crie aplicações React usando Arquitetura Limpa sem precisar configurar nada.

É como usar o comando create-react-app, mas mais eficiente e mais fácil de escalar. O objetivo é ajudar a ganhar tempo durante o desenvolvimento.

Guia do usuário – Como desenvolver aplicativos criados com Clean React App.

Clean React App funciona em macOS, Windows e Linux.

Se algo não funcionar, registre um problema no repositório.

Visão geral rápida

npx @rubemfsv/clean-react-app my-app
cd my-app
npm start or npm run dev

Feito. Tudo está configurado e pronto para ser executado!

Este boilerplate contém as seguintes configurações:

Adapter para o Local storage;
Axios como cliente HTTP;
Webpack configurado para ambientes de desenvolvimento e produção;
Testes end-to-end básicos configurados com Cypress;
Testes unitários com Jest;
Husky com pre-push configurado para rodar os testes unitários;
Autenticação com validações;
Camada de validação para reuso das validações;
Alguns hooks para ajudar com as chamadas da API e submissões de formulários;
Configurações para rotas privadas;
Três páginas para ajudar a melhorar a produtividade:
- Página de Login
- Página de Sign up
- Página inicial

É open source. Sintam-se livres para contribuir!

Link: https://www.npmjs.com/package/@rubemfsv/clean-react-app

Clean Architecture: Applying with React

Rubem Vasconcelos — Sun, 24 Jul 2022 12:54:55 +0000

This text is part of a series of texts about Clean Architecture analysis applied with different frameworks and languages.

The purposes of this text are in line with those of the previous text, which are: I. Show an architectural division of a React application using Clean Architecture; II. Guide the implementation of new features in this proposed architecture.

Architectural Division

The initial step is to analyze how the division is performed.

cypress/
src/
  data/
    protocols/
    test/
    usecases/
  domain/
    errors/
    models/
    test/
    usecases/
  infra/
    cache/
    http/
    test/
  main/
    adapters/
    config/
    decorators/
    factories/
      cache/
      decorators/
      http/
      pages/
      usecases/
    routes/
    scripts/
    index.tsx
  presentation/
    assets/
    components/
    hooks/
    pages/
    protocols/
    routes/
    styles/
    test/
  requirements/
  validation/
    errors/
    protocols/
    test/
    validators/

In detail, the purpose of each file structure is the following:

cypress: It contains the application's end-to-end test files (for large projects, this folder is recommended to be in a separate project, so that the team responsible for e2e tests can take care of it, as they do not need to know the project code).
src: Contains all files needed for the application.
- Data: The data folder represents the data layer of the Clean Architecture, being dependent on the domain layer. Contains the implementations of business rules that are declared in domain.
- Domain: Represents the domain layer of the Clean Architecture, the innermost layer of the application, not having any dependency on any other layer, where it contains the business rules.
- Infra: This folder contains the implementations referring to the HTTP protocol and the cache, it is also the only place where you will have access to external dependencies related to these two items mentioned. This folder also contains most of the external libraries.
- Main: It corresponds to the main layer of the application, where the interfaces developed in the presentation layer are integrated with the business rules created in the folders that represent the innermost layers of the Clean Architecture. All this is due to the use of design patterns such as Factory Method, Composite and Builder.
- Presentation: This folder contains the visual part of the application, with its pages, components, hooks, assets and styling.
Requirements: Contains documented system requirements.
Validation: Where it contains the implementations of the validations used in the fields.

Unlike the approach with Flutter - where there was a central folder where all the tests were concentrated - in this approach the tests are located in the respective folders inside the src.

Implementation Guide

In this section, a recommended logical sequence will be described for a better implementation performance of React systems using this architecture.

In order to simplify the explanation, unit tests will not be described in detail. However, it is strongly recommended to start with unit tests before development (TDD) of each step using the requirements to support the scenarios. And after finalizing the scenarios, test the end to end flow (if it is one of the main ones, keep in mind the test pyramid).

The following demonstration is the creation of the Login flow to log into an application.

First step: Create business rules in the domain layer

Inside src/domain/usecases, create authentication.ts. This file will be an interface that will describe the authentication business rule.

import { AccountModel } from '@/domain/models/';

export interface IAuthentication {
  auth(params: Authentication.Params): Promise<Authentication.Model>;
}

export namespace Authentication {
  export type Params = {
    email: string;
    password: string;
  };

  export type Model = AccountModel;
}

As we can see, it is an interface that has an auth() function that receives the Authentication.Params which are declared in a namespace below - containing the parameters type (email and password) and the model type (AccountModel) - and expects to return an Authentication.Model asynchronously.

AccountModel is a named export of the model created in src/domain/models that represents the token that is returned after authentication to persist the session.

export type AccountModel = {
  accessToken: string;
};

Second step: Implement the rules in the data layer

In this layer, we create the use case to implement the rule created previously in the domain layer, but inside src/data/usecases.

The file usually looks like the example below.

import { IHttpClient, HttpStatusCode } from '@/data/protocols/http';
import { UnexpectedError, InvalidCredentialsError } from '@/domain/errors';
import { IAuthentication, Authentication } from '@/domain/usecases';

export class RemoteAuthentication implements IAuthentication {
  constructor(
    private readonly url: string,
    private readonly httpClient: IHttpClient<RemoteAuthenticationamespace.Model>
  ) {}

  async auth(
    params: Authentication.Params
  ): Promise<RemoteAuthenticationamespace.Model> {
    const httpResponse = await this.httpClient.request({
      url: this.url,
      method: 'post',
      body: params,
    });

    switch (httpResponse.statusCode) {
      case HttpStatusCode.ok:
        return httpResponse.body;
      case HttpStatusCode.unauthorized:
        throw new InvalidCredentialsError();
      default:
        throw new UnexpectedError();
    }
  }
}

export namespace RemoteAuthenticationamespace {
  export type Model = Authentication.Model;
}

As we can see, the RemoteAuthentication class implements the IAuthentication interface, receiving the HTTP client and the url for the request. In the auth() function it receives the parameters, and calls the httpClient passing the url, the method (in this case it is post) and the body (which are the parameters). This return is a httpResponse of the type referring to the Authentication.Model that has a response status code, and which, depending on its result, gives the respective return - and may return the value expected by the request or an error.

The status codes are the HTTP:

export enum HttpStatusCode {
  ok = 200,
  created = 201,
  noContent = 204,
  badRequest = 400,
  unauthorized = 401,
  forbidden = 403,
  notFound = 404,
  serverError = 500,
}

Third step: Implement the pages in the presentation layer

To simplify the understanding, only code snippets referring to the authentication function call will be presented. The Login screen contains more actions and details that go beyond authentication. Consider the page prototype below for easier visualization.

In src/presentation/pages/ the Login page will be created, which is composed by components, methods and functions. The component that calls the authentication function is the <Button/> that is contained in the form to get the input values, as shown in the following code snippet:

<form
  data-testid="loginForm"
  className={Styles.form}
  onSubmit={handleSubmit}
> 
  <Input
    autoComplete="off"
    title="Enter your e-mail"
    type="email"
    name="email"
  />
  <Input
    autoComplete="off"
    title="Enter your password"
    type="password"
    name="password"
    minLength={6}
  />
  <Button
    className={Styles.loginBtn}
    type="submit"
    disabled={state.isFormInvalid}
    title="Login"
    data-testid="loginButton"
  />
</form>

When clicking on the Button, the handleSubmit() that is in the onSubmit of the form is called.

const handleSubmit = async (
    event: React.FormEvent<HTMLFormElement>
  ): Promise<void> => {
    event.preventDefault();
    try {
      const account = await authentication.auth({
        email: state.email,
        password: state.password,
      });

      setCurrentAccount(account);
      history.replace('/');
    } catch (error) {
      // Error handling here
    }
  };

Where the authentication.auth() on click will call a factory (we'll see later) to do the authentication. In this case, it is passing the parameters captured by the input and the value returned from the request is saved in the cache through setCurrentAccount(account).

Fourth step: Connect all layers for requests to work

After everything is implemented, now just connect all the parts. For this, the design pattern Factory Method is used.

Inside src/main/factories/usecases we create the factory of the use case being implemented. In the case of this example, it is related to authentication.

The makeRemoteAuthentication is created, which returns the RemoteAuthentication that receives as a parameter the factory of the Http Client and the factory that creates the URL. The URL of the API you want to request is passed as a parameter along with the factory that creates the URL. In the example it is the URL that ends with /login.

import { RemoteAuthentication } from '@/data/usecases/';
import { IAuthentication } from '@/domain/usecases';
import { makeAxiosHttpClient, makeApiUrl } from '@/main/factories/http';

export const makeRemoteAuthentication = (): IAuthentication => {
  const remoteAuthentication = new RemoteAuthentication(
    makeApiUrl('/login'),
    makeAxiosHttpClient()
  );

  return remoteAuthentication;
};

After that, in src/main/factories/pages, the folder for the Login factories is created. In pages with forms, form validations are also injected, but as the focus of this text is on integrations, we will leave this point out of the explanation.

import React from 'react';
import { Login } from '@/presentation/pages';
import { makeRemoteAuthentication } from '@/main/factories/usecases/';

const makeLogin: React.FC = () => {
  const remoteAuthentication = makeRemoteAuthentication();

  return (
    <Login
      authentication={remoteAuthentication}
    />
  );
};

export default makeLogin;

A makeLogin const representing the factory is created. It has makeRemoteAuthentication which is injected inside the Login page created in the presentation layer so that the page has access to these requests.

Fifth step: Apply the page created in the application

Finally, it is necessary to call the Login factory in the application, so that it can be accessed by the user.

In the router.tsx file located in src/main/routes, add the factory page created into the Switch inside BrowserRouter. The route is passed in the path, in this case it is /login, and the page in the component, which in this case is the pointer to the makeLoginPage factory . This logic is used with all other pages, only changing from Route to PrivateRoute if the route is authenticated. The code looks like this below.

const Router: React.FC = () => {
  return (
    <ApiContext.Provider
      value={{
        setCurrentAccount: setCurrentAccountAdapter,
        getCurrentAccount: getCurrentAccountAdapter,
      }}
    >
      <BrowserRouter>
        <Switch>
          <Route exact path="/login" component={makeLogin} />
          <PrivateRoute exact path="/" component={makeDashboard} />
        </Switch>
      </BrowserRouter>
    </ApiContext.Provider>
  );
};

Conclusion

Clean Architecture despite being a bit complex to understand and implement at the beginning - and even seem redundant -, abstractions are necessary. Several design patterns are applied to ensure the quality and independence of the code, facilitating the evolution and independent maintenance of the framework. In cases like this, if you want to change the framework from React to Angular or any other Typescript based framework, just change the presentation layer and make adjustments to the dependencies.

Following the development process and understanding why you are doing it in such a way makes code production easier. After a while it ends up being done naturally, as it has a linear development process: I. Use case in the domain layer; II. Use case in the data layer; III. Creation of UI in the presentation layer; IV. Creation of factories to integrate all layers into the main layer; V. And the call of the main factory in the application routes.

As the example has many abstracted parts, it is recommended that you read the code for the hidden parts for a better understanding. In this repository you can access abstracted code similar to the one given in this example.

You can also access this architecture just by running the npx @rubemfsv/clean-react-app my app command, similar to create-react-app, but in a cleaner and more scalable way. Find out how to do it reading this post.

References

Rodrigo Manguinho https://github.com/rmanguinho/clean-react
MARTIN, Robert C. Clean Architecture: A Craftsman’s Guide to Software Structure and Design. 1st. ed. USA: Prentice Hall Press, 2017. ISBN 0134494164.

Set Up a React App Using Clean Architecture by Running One Command

Rubem Vasconcelos — Mon, 18 Jul 2022 17:20:00 +0000

Create React apps using Clean Architecture with no build configuration.

It's like create-react-app, but more efficient and easier to scale. The purpose is to help improve time during development.

User Guide – How to develop apps bootstrapped with Clean React App.

Clean React App works on macOS, Windows, and Linux.

If something doesn’t work, please file an issue.

Quick Overview

npx @rubemfsv/clean-react-app my-app
cd my-app
npm start or npm run dev

Done. Everything is set up and ready to run.

This boilerplate contains the following settings:

Local storage adapter;
Axios as HTTP Client;
Webpack configured for development and production environments;
Basic end-to-end test settings with Cypress;
Unit tests with Jest;
Husky with pre-push to run unit tests;
Authentication with validations;
Validation layer for reuse of validations;
Some hooks to help with API calls and form submissions;
Private route configured;
Three pages to help improve productivity:
- Login page
- Sign up page
- Dashboard

It's open source. Feel free to contribute!

Link: https://www.npmjs.com/package/@rubemfsv/clean-react-app

Arquitetura Limpa: Aplicando com React

Rubem Vasconcelos — Fri, 15 Jul 2022 17:18:00 +0000

Esse texto faz parte de uma série de textos sobre análise da Arquitetura Limpa aplicada com frameworks e linguagens distintas.

Os propósitos deste texto seguem alinhados com os do texto anterior, sendo eles: I. Mostrar uma divisão arquitetural de uma aplicação React usando Arquitetura Limpa; II. Guiar a implementação de novas features nesta arquitetura proposta.

Divisão Arquitetural

O passo inicial é analisar como é feita a divisão.

cypress/
src/
  data/
    protocols/
    test/
    usecases/
  domain/
    errors/
    models/
    test/
    usecases/
  infra/
    cache/
    http/
    test/
  main/
    adapters/
    config/
    decorators/
    factories/
      cache/
      decorators/
      http/
      pages/
      usecases/
    routes/
    scripts/
    index.tsx
  presentation/
    assets/
    components/
    hooks/
    pages/
    protocols/
    routes/
    styles/
    test/
  requirements/
  validation/
    errors/
    protocols/
    test/
    validators/

Em detalhes, o propósito de cada estrutura de arquivos é o seguinte:

cypress: Contém os arquivos de teste end to end da aplicação (para projetos grandes, essa pasta é recomendável que seja em um projeto a parte, para que o time responsável pelos testes e2e cuide dele, uma vez que não precisa conhecer o código do projeto).
src: Contém todos os arquivos necessários para o sistema.
- Data: A pasta data representa a camada de dados da Arquitetura Limpa, sendo dependente da camada de domínio. Contém as implementações das regras de negócio que são declaradas no domain.
- Domain: Representa a camada de domínio da Arquitetura Limpa, a camada mais interna da aplicação, não apresentando dependência com nenhuma outra camada, onde contém as regras de negócio.
- Infra: Essa pasta contém as implementações referentes ao protocolo HTTP e ao cache, também é único local onde terá acesso a dependências externas relacionadas para esses dois itens citados. Aqui também é onde está contido a maioria das bibliotecas externas.
- Main: Corresponde a camada principal da aplicação, ponto que ocorre a integração das interfaces desenvolvidas na camada de UI, com as regras de negócio criadas nas pastas que representam as camadas mais internas da Arquitetura Limpa. Tudo isso se dá devido ao uso de padrões de projetos como Factory Method, Composite e Builder.
- Presentation: Nesta pasta contém a parte visual da aplicação, com suas páginas, componentes, hooks, assets e estilizações.
Requirements: Contém os requisitos do sistema documentados.
Validation: Onde contém as implementações das validações utilizadas nos campos.

Diferente da abordagem com Flutter onde havia uma pasta central que se concentravam todos os testes, nessa abordagem os testes se encontram nas respectivas pastas dentro da src.

Guia de Implementação

Nesta seção será descrita uma sequência lógica recomendada para um melhor desempenho de implementação de sistemas React utilizando esta arquitetura.

Para finalidade de simplificar a explicação, não será descrito em detalhes os testes unitários. No entanto, é fortemente recomendado começar pelos testes unitários antes do desenvolvimento (TDD) de cada passo utilizando os requirements para embasar os cenários. E após finalizar os cenários, fazer o teste end to end do fluxo (se for um dos principais, ter em mente a pirâmide de testes).

A demonstração a seguir é da criação do fluxo de Login para entrar em uma aplicação.

Primeiro passo: Criar as regras de negócio na camada de domínio

Dentro de src/domain/usecases, criar o authentication.ts. Esse arquivo será uma interface que vai descrever a regra de negócio da autenticação.

import { AccountModel } from '@/domain/models/';

export interface IAuthentication {
  auth(params: Authentication.Params): Promise<Authentication.Model>;
}

export namespace Authentication {
  export type Params = {
    email: string;
    password: string;
  };

  export type Model = AccountModel;
}

Como vemos, essa interface tem um método auth() que recebe os parâmetros Authentication.Params que são declarados num namespace abaixo - contendo o tipo dos parâmetros (email e password) e o tipo do model (AccountModel) - e espera retornar um Authentication.Model de maneira assíncrona.

O AccountModel é uma exportação nomeada do model criado em src/domain/models que representa o token que é retornado após a autenticação para persistir a sessão.

export type AccountModel = {
  accessToken: string;
};

Segundo passo: Implementar as regras na camada de dados

Nessa camada, criamos o caso de uso para implementar a interface criada anteriormente na camada de domínio, porém dentro de src/data/usecases.

O arquivo tende a ficar como o exemplo abaixo.

import { IHttpClient, HttpStatusCode } from '@/data/protocols/http';
import { UnexpectedError, InvalidCredentialsError } from '@/domain/errors';
import { IAuthentication, Authentication } from '@/domain/usecases';

export class RemoteAuthentication implements IAuthentication {
  constructor(
    private readonly url: string,
    private readonly httpClient: IHttpClient<RemoteAuthenticationamespace.Model>
  ) {}

  async auth(
    params: Authentication.Params
  ): Promise<RemoteAuthenticationamespace.Model> {
    const httpResponse = await this.httpClient.request({
      url: this.url,
      method: 'post',
      body: params,
    });

    switch (httpResponse.statusCode) {
      case HttpStatusCode.ok:
        return httpResponse.body;
      case HttpStatusCode.unauthorized:
        throw new InvalidCredentialsError();
      default:
        throw new UnexpectedError();
    }
  }
}

export namespace RemoteAuthenticationamespace {
  export type Model = Authentication.Model;
}

Como podemos observar, a classe RemoteAuthentication implementa a interface IAuthentication, recebendo o cliente HTTP e a url para a requisição. No método auth() ele recebe os parâmetros, e chama o httpClient passando a url, o método (nesse caso é o post) e o body (que são os parâmetros). Esse retorno é uma httpResponse do tipo referente ao Authentication.Model que tem um código de status de resposta, e que a depender do seu resultado, dá o respectivo retorno - podendo retornar o valor esperado pela requisição ou um erro.

Os códigos de status são os HTTP:

export enum HttpStatusCode {
  ok = 200,
  created = 201,
  noContent = 204,
  badRequest = 400,
  unauthorized = 401,
  forbidden = 403,
  notFound = 404,
  serverError = 500,
}

Terceiro passo: Implementar as páginas na camada de presentation

Para simplificar o entendimento, será apresentado apenas trechos de códigos referentes a chamada do método de autenticação. A página de Login contém mais ações e detalhes que vão além da autenticação. Levar em consideração o protótipo da página abaixo para facilitar a visualização.

Em src/presentation/pages/ será criada a página de Login que é composta por componentes, métodos e funções. O componente que chama o método de autenticação é o <Button/> que está contido no formulário para pegar os valores dos inputs, conforme o trecho de código a seguir:

<form
  data-testid="loginForm"
  className={Styles.form}
  onSubmit={handleSubmit}
> 
  <Input
    autoComplete="off"
    title="Digite seu e-mail"
    type="email"
    name="email"
  />
  <Input
    autoComplete="off"
    title="Digite sua senha"
    type="password"
    name="password"
    minLength={6}
  />
  <Button
    className={Styles.loginBtn}
    type="submit"
    disabled={state.isFormInvalid}
    title="Entrar"
    data-testid="loginButton"
  />
</form>

Ao clicar no Button, é chamado o handleSubmit() que está no onSubmit do form.

const handleSubmit = async (
    event: React.FormEvent<HTMLFormElement>
  ): Promise<void> => {
    event.preventDefault();
    try {
      const account = await authentication.auth({
        email: state.email,
        password: state.password,
      });

      setCurrentAccount(account);
      history.replace('/');
    } catch (error) {
      // Error handling here
    }
  };

Onde o authentication.auth() clicado chamará uma factory (veremos mais a seguir) para fazer a autenticação. Nesse caso está passando os parâmetros capturados pelo input e o valor retornado da requisição é salvo no cache através do setCurrentAccount(account);.

Quarto passo: Conectar todas as camadas para que as requisições funcionem

Após tudo implementado, agora basta conectar todas as partes. Para isso, é utilizado o padrão de projeto Factory Method.

Dentro de src/main/factories/usecases, criamos a factory do caso de uso que está sendo implementado. No caso desse exemplo, é o relacionado a autenticação.

É criado o makeRemoteAuthentication, que retorna o RemoteAuthentication que recebe como parâmetro a factory que cria a URL e a factory do Http Client. É passado como parâmetro a URL da API que deseja requisitar junto da factory que cria a URL. No exemplo é a URL que finaliza com /login.

import { RemoteAuthentication } from '@/data/usecases/';
import { IAuthentication } from '@/domain/usecases';
import { makeAxiosHttpClient, makeApiUrl } from '@/main/factories/http';

export const makeRemoteAuthentication = (): IAuthentication => {
  const remoteAuthentication = new RemoteAuthentication(
    makeApiUrl('/login'),
    makeAxiosHttpClient()
  );

  return remoteAuthentication;
};

Após isso, em src/main/factories/pages, é criada a pasta para as factories do Login. Em páginas com formulário também são injetadas validações, porém como o foco desse texto são as integrações, deixaremos esse ponto de fora da explicação.

import React from 'react';
import { Login } from '@/presentation/pages';
import { makeRemoteAuthentication } from '@/main/factories/usecases/';

const makeLogin: React.FC = () => {
  const remoteAuthentication = makeRemoteAuthentication();

  return (
    <Login
      authentication={remoteAuthentication}
    />
  );
};

export default makeLogin;

É criada uma const makeLogin que representa a factory. Ela possui o makeRemoteAuthentication que é injetado dentro da página de Login criada na camada de presentation para que a página tenha acesso a essas requisições.

Quinto passo: Aplicar a página criada na aplicação

Por fim, é necessário adicionar a factory do Login nas rotas da aplicação para que ela seja acessada pelos usuários.

No arquivo router.tsx que fica localizado em src/main/routes, adicionar a factory da página criada dentro do Switch do BrowserRouter. É passado no path a rota, no caso é a /login, e a página no component, que no caso é o ponteiro para a factory makeLoginPage. Essa lógica é utilizada com todas as outras páginas, alterando apenas de Route para PrivateRoute caso a rota seja autenticada. O código parecido com este abaixo.

const Router: React.FC = () => {
  return (
    <ApiContext.Provider
      value={{
        setCurrentAccount: setCurrentAccountAdapter,
        getCurrentAccount: getCurrentAccountAdapter,
      }}
    >
      <BrowserRouter>
        <Switch>
          <Route exact path="/login" component={makeLogin} />
          <PrivateRoute exact path="/" component={makeDashboard} />
        </Switch>
      </BrowserRouter>
    </ApiContext.Provider>
  );
};

Conclusão

A Arquitetura Limpa apesar de ser um pouco complexa de se entender e implementar no começo - e até parecer redundante -, as abstrações são necessárias. São aplicados diversos padrões de projetos para garantir a qualidade e independência do código, facilitando a evolução e manutenção independente de framework. Em casos como esse, se desejar mudar o framework de React para Angular ou qualquer outro baseado em Typescript, basta mudar a camada de apresentação e fazer ajustes nas dependências.

Seguir o processo de desenvolvimento e entender o porquê está fazendo de tal maneira facilita a produção do código. Após um tempo acaba sendo feito de maneira natural, pois tem um processo linear de desenvolvimento: I. Caso de uso na camada de domínio; II. Caso de uso na camada de dados; III. Criação das interfaces na camada de presentation; IV. Criação das factories para integrar todas as camadas na camada principal; V. E a chamada da factory principal nas rotas da aplicação.

Pelo exemplo ter muitas partes abstraídas, é recomendável a leitura do código das partes ocultas para uma maior compreensão. Nesse repositório você consegue ter acesso a códigos abstraídos similares ao desse exemplo dado.

Você também pode ter acesso a essa arquitetura rodando apenas o comando npx @rubemfsv/clean-react-app my app, similar ao create-react-app, mas de uma maneira mais limpa e escalável.

Referências

Rodrigo Manguinho https://github.com/rmanguinho/clean-react
MARTIN, Robert C. Clean Architecture: A Craftsman’s Guide to Software Structure and Design. 1st. ed. USA: Prentice Hall Press, 2017. ISBN 0134494164.

Clean Architecture: Applying with Flutter

Rubem Vasconcelos — Sat, 09 Jul 2022 18:45:20 +0000

Before starting to read this text, it is recommended to have notions of some basic concepts such as Clean Architecture and SOLID, as they make it easier to understand what will be presented.

This text has two purposes: I. Show an architectural division of a Flutter application using Clean Architecture; II. Guide the implementation of new features in this proposed architecture.

The analyzed code is based on the Clean Architecture approach proposed by Rodrigo Manguinho in his Flutter course. His approach is aligned with the original proposal by Robert Martin.

Architectural Division

The first step is to analyze how the division is done.

android/
ios/
lib/
  data/
    cache/
    http/
    models/
    usecases/
  domain/
    entities/
    helpers/
    usecases/
  infra/
    cache/
    http/
  main/
    builders/
    composites/
    decorators/
    factories/
      cache/
      http/
      pages/
      usecases/
    main.dart
  presentation/
    mixins/
    presenters/
    protocols/
  ui/
    assets/
    components/
    helpers/
    mixins/
    pages/
  validation/
    protocols/
    validators/
requirements/
    bdd_specs/
    checklists/
    usecases/
test/
    data/
    domain/
    infra/
    main/
    mocks/
    presentation/
    ui/
    validation/

And from there, we can make associations with the Clean Architecture theory for an easier understanding of division of responsibilities.

Next, let's take a closer look at the purpose of each file structure.

Android: Contains the files needed to build the application on android systems.
iOS: Contains the files needed to build the application on iOS systems.
Lib: Contains all files needed for the application.
- Data: The data folder represents the data layer of the Clean Architecture, being dependent on the domain layer. Contains the implementations of business rules that are declared in domain.
- Domain: Represents the domain layer of the Clean Architecture, the innermost layer of the application, not having any dependency on any other layer, where it contains the business rules.
- Infra: This folder contains the implementations referring to the HTTP protocol and the cache, it is also the only place where you will have access to external dependencies related to these two items mentioned.
- Main: It corresponds to the main layer of the application, where the interfaces developed in the UI layer are integrated with the business rules created in the folders that represent the innermost layers of the Clean Architecture. All this is due to the use of design patterns such as Factory Method, Composite and Builder.
- Presentation: This layer is where the data is prepared to be consumed in the UI, handling the logic behind the screens.
- UI: Contains the components and visual interfaces that are seen in the system, this is where the screens are created.
- Validation: Where it contains the implementations of the validations used in the fields (ex: minimum amount of characters, required field, valid email, among others).
Requirements: Contains documented system requirements, this folder may or may not have all of the following subfolders, it depends a lot on how the team works.
- Bdd_specs: Contains files written in Gherkin language to describe the expected behavior of the system.
- Checklist: It contains the description of the behavior of the pages, in order to facilitate during the unit tests, to know what to validate and what to expect.
- Usecases: It contains the expected behavior of the use cases of the system, where it describes the variations of the business rules to facilitate the unit tests and implementation.
Test: It contains all the unit tests of the application, each internal folder represents the layer that the tests belong to, and the mocks folder contains the mocks used in the tests.

Implementation Guide

After understanding the reason for the division and what responsibilities are contained in each folder of the structure, a recommended logical sequence for a better implementation performance using this architecture will be described.

The following demonstration is the creation of the Login flow to log into an application.

First step: Create business rules in the domain layer

Inside lib/domain/usecases, create authentication.dart. This file will be an abstract class that will describe the authentication business rule.

import '../entities/entities.dart';

abstract class Authentication {
  Future<AccountEntity> auth(AuthenticationParams params);
}

class AuthenticationParams {
  final String email;
  final String password;

  AuthenticationParams({required this.email, required this.password});
}

As we can see, it is an abstract class that has an auth() method that receives the AuthenticationParams parameters that are declared below (email and password), and expects to return an AccountEntity asynchronously through the Future.

AccountEntity is a class created in lib/domain/entities which represents the token that is returned after authentication to persist the session.

class AccountEntity {
  final String token;

  AccountEntity({required this.token});
}

Second step: Implement the rules in the data layer

In this layer, we create the use case to implement the rule created previously in the domain layer, but inside lib/data/usecases.

The file usually looks like the example below.

import '../../../domain/entities/entities.dart';
import '../../../domain/helpers/helpers.dart';
import '../../../domain/usecases/usecases.dart';

import '../../http/http.dart';
import '../../models/models.dart';

class RemoteAuthentication implements Authentication {
  final HttpClient httpClient;
  final String url;

  RemoteAuthentication({required this.httpClient, required this.url});

  Future<AccountEntity> auth(AuthenticationParams params) async {
    final body = RemoteAuthenticationParams.fromDomain(params).toJson();
    try {
      final hpptResponse =
          await httpClient.request(url: url, method: 'post', body: body);

      return RemoteAccountModel.fromJson(hpptResponse).toEntity();
    } on HttpError catch (error) {
      throw error == HttpError.unauthorized
          ? DomainError.invalidCredentials
          : DomainError.unexpected;
    }
  }
}

class RemoteAuthenticationParams {
  final String email;
  final String password;

  RemoteAuthenticationParams({required this.email, required this.password});

  factory RemoteAuthenticationParams.fromDomain(AuthenticationParams params) =>
      RemoteAuthenticationParams(
          email: params.email, password: params.password);

  Map toJson() => {'email': email, 'password': password};
}

As we can see, the RemoteAuthentication class implements the Authentication abstract class, receiving the HTTP client and the url for the request. In the auth() method it receives the parameters, and calls the RemoteAuthenticationParams.fromDomain(params) factory created below with the purpose of converting what comes in the standard format to the json format to be sent in the HTTP request inside the body. After that, the request is made and the value returned in httpResponse is stored, and this httpResponse is returned in the method inside a model in order to convert the result to the standard format to work (entity) through RemoteAccountModel.fromJson( hpptResponse).toEntity().

This factory and model are created in this layer with the purpose of not polluting the domain layer, because what happens in the data layer should not influence what happens in the domain layer.

For the sake of curiosity, the implementation of RemoteAccountModel is below. It takes an accessToken in json format and converts it to an Entity.

import '../../domain/entities/entities.dart';
import '../http/http.dart';

class RemoteAccountModel {
  final String accessToken;

  RemoteAccountModel(this.accessToken);

  factory RemoteAccountModel.fromJson(Map json) {
    if (!json.containsKey('accessToken')) {
      throw HttpError.invalidData;
    }
    return RemoteAccountModel(json['accessToken']);
  }

  AccountEntity toEntity() => AccountEntity(token: accessToken);
}

Third step: Implement the screens in the UI layer

To simplify the understanding, only code snippets referring to the authentication method call will be presented. The Login screen contains more actions and details that go beyond authentication. Consider the screen prototype below for easier visualization.

In lib/ui/pages/ you will need at least two files: I. login_page.dart, which will be the Login page; II. login_presenter.dart which will contain the abstract class with the methods and streams that are used on the page, and the implementation of this abstract class takes place in the presentation layer.

The login_presenter.dart file is similar to the example below.

import 'package:flutter/material.dart';

abstract class LoginPresenter implements Listenable {
  void validateEmail(String email);
  void validatePassword(String password);

  Future<void> auth();
}

And the code below is for the Login button.

class LoginButton extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final presenter = Provider.of<LoginPresenter>(context);

    return StreamBuilder<bool>(
      stream: presenter.isFormValidStream,
      builder: (context, snapshot) {
        return ElevatedButton(
          onPressed: snapshot.data == true ? presenter.auth : null,
          child: Text(R.translations.enterButtonText.toUpperCase()),
        );
      },
    );
  }
}

The auth() method when clicked on onPressed calls the presenter to do the authentication. In this case, you are not passing parameters in auth() because the parameters are taken from the presenter when interacting with the screen (the validateEmail() and validatePassword() declared above in the page presenter are used). We will see more details in the next step.

Fourth step: Implement the UI's abstract presenter class in the presentation layer

To make it easier to work with Streams, it is recommended to use the GetX library (or any other one of your choice) to make it less verbose. The choice for GetX is due to its great support and being constantly updated.

In lib/presentation/presenters, getx_login_presenter.dart is created. It is a GetxLoginPresenter class that extends GetxController and implements LoginPresenter. Although the example below has Validation and SaveCurrentAccount, we will focus only on Authentication.

import 'dart:async';
import 'package:get/get.dart';

import '../../ui/pages/login/login_presenter.dart';
import '../../domain/helpers/domain_error.dart';
import '../../domain/usecases/usecases.dart';
import '../protocols/protocols.dart';

class GetxLoginPresenter extends GetxController
  implements LoginPresenter {
  final Validation validation;
  final Authentication authentication;
  final SaveCurrentAccount saveCurrentAccount;

  String? _email;
  String? _password;

  GetxLoginPresenter({
    required this.validation,
    required this.authentication,
    required this.saveCurrentAccount,
  });

  void validateEmail(String email) {
    _email = email;
    // Validation code here
  }

  void validatePassword(String password) {
    _password = password;
    // Validation code here
  }

  Future<void> auth() async {
    try {
      final account = await authentication.auth(AuthenticationParams(
        email: _email!,
        password: _password!,
      ));
      await saveCurrentAccount.save(account);
    } on DomainError catch (error) {
      // Handle errors here
    }
  }
}

In the validateEmail(String email) and validatePassword(String password) methods, the user's email and password are captured when typing in the Inputs of the Login screen. In auth(), this is where there is a call to the previously implemented authentication method, which receives the email and password captured by the previous validates.

The call authentication.auth(AuthenticationParams(email: _email!, password: _password!)) returns a token (as explained earlier), is assigned to a variable called account and then cached via saveCurrentAccount.save( account) (this point was not explained in this text, but it is through it that the user session persists on the device).

Fifth step: Connect all layers for requests to work

After everything is implemented, now just connect all the parts. For this, the design pattern Factory Method is used.

Inside lib/main/factories/usecases we create the factory of the use case being implemented. In the case of this example, it is related to authentication.

The authentication_factory.dart is created, which returns the RemoteAuthentication that receives as a parameter the factory of the Http Client and the factory that creates the URL. The URL of the API you want to request is passed as a parameter along with the factory that creates the URL. In the example it is the URL that ends with /login.

import '../../../domain/usecases/usecases.dart';
import '../../../data/usecases/usecases.dart';
import '../factories.dart';

Authentication makeRemoteAuthentication() {
  return RemoteAuthentication(
    httpClient: makeHttpAdapter(),
    url: makeApiUrl('login'),
  );
}

After that, in lib/main/factories/pages, the folder for the Login factories is created. For this explanation, we will focus on login_page_factory.dart and login_presenter_factory.dart.

First, the login_presenter_factory.dart is made, which is a Widget that returns the GetxLoginPresenter. This presenter was created previously, and inside it is injecting the authentication factories (which was created just above) and the validation and saving token in the cache (which were not covered in this text, but follow the same premises of _ makeRemoteAuthentication_) .

import '../../factories.dart';
import '../../../../presentation/presenters/presenters.dart';
import '../../../../ui/pages/pages.dart';

LoginPresenter makeGetxLoginPresenter() {
  return GetxLoginPresenter(
    authentication: makeRemoteAuthentication(),
    validation: makeLoginValidation(),
    saveCurrentAccount: makeLocalSaveCurrentAccount(),
  );
}

Then, following the same line of thought, the factory of the Login page is made. Like the factory of the presenter, it's a Widget, but in this case it returns the LoginPage with the factory of the presenter created earlier being injected as a parameter.

import 'package:flutter/material.dart';
import '../../../../ui/pages/pages.dart';
import '../../factories.dart';

Widget makeLoginPage() {
  return LoginPage(makeGetxLoginPresenter());
}

Sixth step: Apply the screen created in the application

Finally, it is necessary to call the Login factory in the application, so that it can be accessed by the user.

In the main.dart file located in lib/main, add the factory page created into the page array (getPages). In the route, is passed the name of the rout - in this case it is /login - and the page, which in this case is the pointer to the factory makeLoginPage. This logic is used with all other pages. The code looks like it is below.

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:get/get.dart';

import '../ui/components/components.dart';
import 'factories/factories.dart';

void main() {
  runApp(App());
}

class App extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    SystemChrome.setSystemUIOverlayStyle(SystemUiOverlayStyle.light);
    final routeObserver = Get.put<RouteObserver>(RouteObserver<PageRoute>());

    return GetMaterialApp(
      title: 'Flutter Clean App',
      debugShowCheckedModeBanner: false,
      theme: makeAppTheme(),
      navigatorObservers: [routeObserver],
      initialRoute: '/',
      getPages: [
        GetPage(
            name: '/login', page: makeLoginPage, transition: Transition.fadeIn),
      ],
    );
  }
}

Conclusion

Although it is a little complex to understand at first and seems a bit redundant, abstractions are necessary. Various design patterns are applied to ensure code quality and independence, facilitating evolution and maintenance.

Following the development process and understanding why you are doing it in such a way makes code production easier. After a while it ends up being done naturally, as it has a linear development process: I. Use case in the domain layer; II. Use case in the data layer; III. UI creation; IV. Creation of logics to call the request in the presentation layer; V. Creation of factories to integrate all layers into the main layer; VI. And then the call of the main factory in the application routes so that it is available to the user.

Despite having many abstracted parts, it is recommended to read the code of the hidden parts for a better understanding. In this repository from Rodrigo Manguinho's course you can access these abstracted codes.

References

Rodrigo Manguinho https://github.com/rmanguinho/clean-flutter-app
MARTIN, Robert C. Clean Architecture: A Craftsman’s Guide to Software Structure and Design. 1st. ed. USA: Prentice Hall Press, 2017. ISBN 0134494164.

Arquitetura Limpa: Aplicando com Flutter

Rubem Vasconcelos — Fri, 01 Jul 2022 21:21:07 +0000

Antes de iniciar a leitura desse texto, é recomendável ter noções de alguns conceitos básicos como Arquitetura Limpa e SOLID, pois eles facilitam o entendimento do que será apresentado.

Este texto tem dois propósitos: I. Mostrar uma divisão arquitetural de uma aplicação Flutter usando Arquitetura Limpa; II. Guiar a implementação de novas features nesta arquitetura proposta.

O código analisado é baseado na abordagem de Arquitetura Limpa proposta por Rodrigo Manguinho em seu curso de Flutter. Sua abordagem segue alinhada com a proposta original de Robert Martin.

Divisão Arquitetural

O primeiro passo é analisar como é feita a divisão.

android/
ios/
lib/
  data/
    cache/
    http/
    models/
    usecases/
  domain/
    entities/
    helpers/
    usecases/
  infra/
    cache/
    http/
  main/
    builders/
    composites/
    decorators/
    factories/
      cache/
      http/
      pages/
      usecases/
    main.dart
  presentation/
    mixins/
    presenters/
    protocols/
  ui/
    assets/
    components/
    helpers/
    mixins/
    pages/
  validation/
    protocols/
    validators/
requirements/
    bdd_specs/
    checklists/
    usecases/
test/
    data/
    domain/
    infra/
    main/
    mocks/
    presentation/
    ui/
    validation/

E a partir daí, podemos fazer associações com a teoria da Arquitetura Limpa para uma compreensão mais fácil da divisão de responsabilidades.

A seguir, vamos ver em detalhes o propósito de cada estrutura de arquivos.

Android: Contém os arquivos necessários para buildar a aplicação em sistemas android.
iOS: Contém os arquivos necessários para buildar a aplicação em sistemas iOS.
Lib: Contém todos os arquivos necessários para a aplicação.
- Data: A pasta data representa a camada de dados da Arquitetura Limpa, sendo dependente da camada de domínio. Contém as implementações das regras de negócio que são declaradas no domain.
- Domain: Representa a camada de domínio da Arquitetura Limpa, a camada mais interna da aplicação, não apresentando dependência com nenhuma outra camada, onde contém as regras de negócio.
- Infra: Essa pasta contém as implementações referentes ao protocolo HTTP e ao cache, também é único local onde terá acesso a dependências externas relacionadas para esses dois itens citados.
- Main: Corresponde a camada principal da aplicação, ponto que ocorre a integração das interfaces desenvolvidas na camada de UI, com as regras de negócio criadas nas pastas que representam as camadas mais internas da Arquitetura Limpa. Tudo isso se dá devido ao uso de padrões de projetos como Factory Method, Composite e Builder.
- Presentation: Nessa camada é onde os dados são preparados para serem consumidos na UI, tratando as lógicas por trás das telas.
- UI: Contém os componentes e interfaces visuais que são vistas no sistema, é aqui que propriamente são criadas as telas.
- Validation: Onde contém as implementações das validações utilizadas nos campos (ex: quantidade mínima de carácteres, campo obrigatório, email válido, dentre outros).
Requirements: Contém os requisitos do sistema documentados, essa pasta pode ou não ter todas as subpastas a seguir, depende muito de como o time trabalha.
- Bdd_specs: Contém os arquivos escritos em linguagem Gherkin para descrever o comportamento esperado do sistema.
- Checklist: Contém a descrição do comportamento das páginas, com o intuito de facilitar durante os testes unitários, para saber o que validar e o que esperar.
- Usecases: Contém o comportamento esperado dos casos de uso do sistema, onde descreve as variações das regras de negócio para facilitar os testes unitários e implementação.
Test: Contém todos os testes unitários da aplicação, cada pasta interna representa a camada que os testes pertencem, e a pasta de mocks contém os mocks utilizados nos testes.

Guia de Implementação

Após compreender a razão da divisão e quais responsabilidades estão contidas em cada pasta da estrutura, será descrita uma sequência lógica recomendada para um melhor desempenho de implementação utilizando esta arquitetura.

A demonstração a seguir é da criação do fluxo de Login para entrar em uma aplicação.

Primeiro passo: Criar as regras de negócio na camada de domínio

Dentro de lib/domain/usecases, criar o authentication.dart. Esse arquivo vai ser uma classe abstrata que vai descrever a regra de negócio da autenticação.

import '../entities/entities.dart';

abstract class Authentication {
  Future<AccountEntity> auth(AuthenticationParams params);
}

class AuthenticationParams {
  final String email;
  final String password;

  AuthenticationParams({required this.email, required this.password});
}

Como vemos, é uma classe abstrata que tem um método auth() que recebe os parâmetros AuthenticationParams que são declarados abaixo (email e password), e espera retornar um AccountEntity de maneira assíncrona através do Future.

O AccountEntity é uma classe criada em lib/domain/entities que representa o token que é retornado após a autenticação para persistir a sessão.

class AccountEntity {
  final String token;

  AccountEntity({required this.token});
}

Segundo passo: Implementar as regras na camada de dados

Nessa camada, criamos o caso de uso para implementar a regra criada anteriormente na camada de domínio, porém dentro de lib/data/usecases.

O arquivo costuma ficar como o exemplo abaixo.

import '../../../domain/entities/entities.dart';
import '../../../domain/helpers/helpers.dart';
import '../../../domain/usecases/usecases.dart';

import '../../http/http.dart';
import '../../models/models.dart';

class RemoteAuthentication implements Authentication {
  final HttpClient httpClient;
  final String url;

  RemoteAuthentication({required this.httpClient, required this.url});

  Future<AccountEntity> auth(AuthenticationParams params) async {
    final body = RemoteAuthenticationParams.fromDomain(params).toJson();
    try {
      final hpptResponse =
          await httpClient.request(url: url, method: 'post', body: body);

      return RemoteAccountModel.fromJson(hpptResponse).toEntity();
    } on HttpError catch (error) {
      throw error == HttpError.unauthorized
          ? DomainError.invalidCredentials
          : DomainError.unexpected;
    }
  }
}

class RemoteAuthenticationParams {
  final String email;
  final String password;

  RemoteAuthenticationParams({required this.email, required this.password});

  factory RemoteAuthenticationParams.fromDomain(AuthenticationParams params) =>
      RemoteAuthenticationParams(
          email: params.email, password: params.password);

  Map toJson() => {'email': email, 'password': password};
}

Como podemos observar, a classe RemoteAuthentication implementa a classe abstrata Authentication, recebendo o cliente HTTP e a url para a requisição. No método auth() ele recebe os parâmetros, e chama a factory RemoteAuthenticationParams.fromDomain(params) criada abaixo com o propósito de converter o que vem no formato padrão para o formato json para ser enviado na requisição HTTP dentro do body. Após isso, é feita a requisição e armazenado o valor retornado em httpResponse, e essa httpResponse é retornada no método dentro de um model com o intuito de converter o resultado para o formato padrão de se trabalhar (entity) através de RemoteAccountModel.fromJson(hpptResponse).toEntity().

Essa factory e model são criadas nessa camada com o propósito de não poluir a camada de domínio, pois o que acontece na camada de dados não deve influenciar o que acontece na de domínio.

Para fim de curiosidade, a implementação do RemoteAccountModel está abaixo. Ele recebe um accessToken no formato de json e o converte para um Entity.

import '../../domain/entities/entities.dart';
import '../http/http.dart';

class RemoteAccountModel {
  final String accessToken;

  RemoteAccountModel(this.accessToken);

  factory RemoteAccountModel.fromJson(Map json) {
    if (!json.containsKey('accessToken')) {
      throw HttpError.invalidData;
    }
    return RemoteAccountModel(json['accessToken']);
  }

  AccountEntity toEntity() => AccountEntity(token: accessToken);
}

Terceiro passo: Implementar as telas na camada de UI

Para simplificar o entendimento, será apresentado apenas trechos de códigos referentes a chamada do método de autenticação. A tela de Login contém mais ações e detalhes que vão além da autenticação. Levar em consideração o protótipo da tela abaixo para facilitar a visualização.

Em lib/ui/pages/ será necessário ao menos dois arquivos: I. login_page.dart, que será a página de Login; II. login_presenter.dart que conterá a classe abstrata com os métodos e streams que são utilizados na página, e a implementação dessa classe abstrata ocorre na camada de presentation.

O arquivo login_presenter.dart é similar ao exemplo abaixo.

import 'package:flutter/material.dart';

abstract class LoginPresenter implements Listenable {
  void validateEmail(String email);
  void validatePassword(String password);

  Future<void> auth();
}

E o código abaixo é do botão de Login.

class LoginButton extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final presenter = Provider.of<LoginPresenter>(context);

    return StreamBuilder<bool>(
      stream: presenter.isFormValidStream,
      builder: (context, snapshot) {
        return ElevatedButton(
          onPressed: snapshot.data == true ? presenter.auth : null,
          child: Text(R.translations.enterButtonText.toUpperCase()),
        );
      },
    );
  }
}

Onde o auth() clicado no onPressed chama o presenter para fazer a autenticação. Nesse caso não está passando parâmetros no auth() por os parâmetros serem pegos no presenter durante a interação com a tela (são usados os validateEmail() e validatePassword() declarados acima no presenter da página). Veremos mais detalhes no próximo passo.

Quarto passo: Implementar a classe abstrata do presenter da UI na camada de presentation

Para facilitar o trabalho com Streams, é recomendado o uso da biblioteca GetX (ou alguma outra da sua preferência) para deixar menos verboso. A escolha pela GetX é devido ao seu grande suporte e estar em constante atualização.

Em lib/presentation/presenters é criado o getx_login_presenter.dart. É uma classe GetxLoginPresenter que extende o GetxController e implementa o LoginPresenter. Apesar do exemplo abaixo ter Validation e SaveCurrentAccount, focaremos no Authentication.

import 'dart:async';
import 'package:get/get.dart';

import '../../ui/pages/login/login_presenter.dart';
import '../../domain/helpers/domain_error.dart';
import '../../domain/usecases/usecases.dart';
import '../protocols/protocols.dart';

class GetxLoginPresenter extends GetxController
  implements LoginPresenter {
  final Validation validation;
  final Authentication authentication;
  final SaveCurrentAccount saveCurrentAccount;

  String? _email;
  String? _password;

  GetxLoginPresenter({
    required this.validation,
    required this.authentication,
    required this.saveCurrentAccount,
  });

  void validateEmail(String email) {
    _email = email;
    // Validation code here
  }

  void validatePassword(String password) {
    _password = password;
    // Validation code here
  }

  Future<void> auth() async {
    try {
      final account = await authentication.auth(AuthenticationParams(
        email: _email!,
        password: _password!,
      ));
      await saveCurrentAccount.save(account);
    } on DomainError catch (error) {
      // Handle errors here
    }
  }
}

Nos métodos validateEmail(String email) e validatePassword(String password) são capturados o email e senha do usuário ao digitar nos Inputs da tela de Login. Em auth(), é onde há a chamada ao método de autenticação implementados anteriormente, que recebem o email e senha capturados pelos validates anteriores.

A chamada authentication.auth(AuthenticationParams(email: _email!, password: _password!)) retorna um token (como explicado anteriormente), é atribuído a uma variável chamada account e em seguida salva em cache através do saveCurrentAccount.save(account) (não foi explicado sobre esse ponto nesse texto, porém é através dele que há a persistência da sessão do usuário no aparelho).

Quinto passo: Conectar todas as camadas para que as requisições funcionem

Após tudo implementado, agora basta conectar todas as partes. Para isso, é utilizado o padrão de projeto Factory Method.

Dentro de lib/main/factories/usecases, criamos a factory do caso de uso que está sendo implementado. No caso desse exemplo, é o relacionado a autenticação.

É criado o authentication_factory.dart, que retorna o RemoteAuthentication que recebe como parâmetro a factory do Http Client e a factory que cria a URL. É passado como parâmetro a URL da API que deseja requisitar junto da factory que cria a URL. No exemplo é a URL que finaliza com /login.

import '../../../domain/usecases/usecases.dart';
import '../../../data/usecases/usecases.dart';
import '../factories.dart';

Authentication makeRemoteAuthentication() {
  return RemoteAuthentication(
    httpClient: makeHttpAdapter(),
    url: makeApiUrl('login'),
  );
}

Após isso, em lib/main/factories/pages, é criada a pasta para as factories do Login. Para essa explicação, focaremos no login_page_factory.dart e login_presenter_factory.dart.

Primeiro, é feito a login_presenter_factory.dart, que é um Widget que retorna o GetxLoginPresenter. Esse presenter foi criado anteriormente, e dentro dele é injetando as factories de autenticação (que foi criado logo a cima) e as de validação e salvar token no cache (que não foram abordadas nesse texto, porém seguem as mesmas premissas da factory de autenticação).

import '../../factories.dart';
import '../../../../presentation/presenters/presenters.dart';
import '../../../../ui/pages/pages.dart';

LoginPresenter makeGetxLoginPresenter() {
  return GetxLoginPresenter(
    authentication: makeRemoteAuthentication(),
    validation: makeLoginValidation(),
    saveCurrentAccount: makeLocalSaveCurrentAccount(),
  );
}

Em seguida, seguindo a mesma linha de pensamento, é feita a factory da página de Login. Como a factory do presenter, é um Widget, mas nesse caso retorna a LoginPage com a factory do presenter criado anteriormente sendo injetado como parâmetro.

import 'package:flutter/material.dart';
import '../../../../ui/pages/pages.dart';
import '../../factories.dart';

Widget makeLoginPage() {
  return LoginPage(makeGetxLoginPresenter());
}

Sexto passo: Aplicar a tela criada na aplicação

Por fim, é necessário chamar a factory do Login na aplicação para que ela consiga ser acessada pelo usuário.

No arquivo main.dart que fica localizado em lib/main, adicionar dentro do array de páginas (getPages) a factory página criada. É passado no name a rota, no caso é a /login, e a página, que no caso é o ponteiro para a factory makeLoginPage. Essa lógica é utilizada com todas as outras páginas. O código fica como está abaixo.

import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:get/get.dart';

import '../ui/components/components.dart';
import 'factories/factories.dart';

void main() {
  runApp(App());
}

class App extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    SystemChrome.setSystemUIOverlayStyle(SystemUiOverlayStyle.light);
    final routeObserver = Get.put<RouteObserver>(RouteObserver<PageRoute>());

    return GetMaterialApp(
      title: 'Flutter Clean App',
      debugShowCheckedModeBanner: false,
      theme: makeAppTheme(),
      navigatorObservers: [routeObserver],
      initialRoute: '/',
      getPages: [
        GetPage(
            name: '/login', page: makeLoginPage, transition: Transition.fadeIn),
      ],
    );
  }
}

Conclusão

Apesar de ser um pouco complexo de se entender no começo e parecer um pouco redundante, as abstrações são necessárias. São aplicados diversos padrões de projetos para garantir a qualidade e independência do código, facilitando a evolução e manutenção.

Seguir o processo de desenvolvimento e entender o porquê está fazendo de tal maneira facilita a produção do código. Após um tempo acaba sendo feito de maneira natural, pois tem um processo linear de desenvolvimento: I. Caso de uso na camada de domínio; II. Caso de uso na camada de dados; III. Criação da UI; IV. Criação das lógicas para chamada da requisição na camada de presentation; V. Criação das factories para integrar todas as camadas na camada principal; VI. E a chamada da factory principal nas rotas da aplicação para que seja disponível para o usuário.

Apesar de ter muitas partes abstraídas, é recomendável a leitura do código das partes ocultas para uma maior compreensão. Nesse repositório do curso do Rodrigo Manguinho você consegue ter acesso a esses códigos abstraídos.

Referências

Rodrigo Manguinho https://github.com/rmanguinho/clean-flutter-app
MARTIN, Robert C. Clean Architecture: A Craftsman’s Guide to Software Structure and Design. 1st. ed. USA: Prentice Hall Press, 2017. ISBN 0134494164.

Clean Architecture: Layers and Boundaries

Rubem Vasconcelos — Thu, 23 Jun 2022 17:26:20 +0000

After understanding about the key concepts of Clean Architecture and some important concepts that surround it such as SOLID and component principles, it is easier to understand about its division into layers and its boundaries.

A system can be defined by three basic components: the UI, the business rules and the database - and in larger systems there are many more components. To explain the concept of layers and boundaries, the example made by MARTIN (2017) will be used, which describes the game of the 1970s called Hunt the Wumpus.

The rules of the game are irrelevant for this example, as the focus will be on the implementation itself.

Considering that a text-based UI is used, it is necessary to decouple the game rules so it can have different languages. The rules will communicate with the UI using an API, regardless of language, and the UI will translate to the requested language. In this way all UI components will be able to make use of the same rules of the game. Assuming that the game state is kept in a persistent store, there is no need for the game rules to know the details, so an API will be created to communicate these rules with the data store component.

The game rules must also not know about the different types of data storage, so the dependencies must be correctly addressed following the Dependency Rule, as seen in the game's basic structure figure (source: MARTIN (2017)).

After this brief description and based on Clean Architecture concepts, it is imagined that clean architecture would be easily applied in this example. However, not all architectural boundaries are clear.

In this example, the language is not the only UI change axis, the communication mechanism can also be varied, such as a chat application, a normal window or text messages. There are countless possibilities for change, which shows that there is an architectural limit defined by these axes of change. Therefore, it is necessary to create an API to cross this limit and isolate the language from the communication mechanism.

The figure above reflects the reformulated game structure (source: MARTIN (2017)), the dotted rectangles are the APIs and the rectangle written "Game Rules" contains the game rules. The Rules of the Game component is positioned at the top of the diagram, as it contains the highest level policies. This organization divides the data flow, being the left side to communicate with the user and the right side for data persistence. As systems grow, the component structure can be divided into several flows with different hierarchies, which makes the architecture increasingly complex.

MARTIN (2017) concludes this issue by stating that the role of the software architect is to assess costs, determine architectural limits and which of these limits should be fully implemented, which should be partially implemented and which should be ignored.

Conclusion

This simple example is meant to show that there are architectural boundaries everywhere, and it's up to software architects to recognize the needs.

It is also necessary to know that implementing these boundaries is something expensive, but at the same time, if not implemented early in development, they can have even greater costs over time.

Martin reinforces that these decisions are not made just once, that it is necessary to observe the evolution of the system, analyze where boundaries may be necessary and what can happen if they do not have well-defined boundaries. He also reinforces the importance of comparing the costs of implementing these boundaries with the cost of ignoring them, always looking to implement the right boundaries at the sweet spot where the cost of implementation is less than the cost of ignoring them.

References

MARTIN, Robert C. Clean Architecture: A Craftsman’s Guide to Software Structure and Design. 1st. ed. USA: Prentice Hall Press, 2017. ISBN 0134494164.