Como documentar a Arquitetura de Software

Os principais aspectos tcnicos relativos ao desenvolvimento de um sistema

Introduo
No ciclo de vida do desenvolvimento de software podemos encontrar diversas etapas e todas
com seus propsitos muito bem definidos, porm, uma que podemos dizer com segurana ser de
extrema importncia a arquitetura do software.
Quando falamos em arquitetura logo nos vem alguns padres como Zechman framework,
TOGAF, DODAF e etc. Esses padres existem para auxiliar e facilitar a arquitetura corporativa
no intuito de prover uma abordagem ao design, planejamento, implementao e governana de
uma arquitetura de informao corporativa.
Mas hoje em dia, com o conceito de agilidade sendo um dos principais diferenciais no
desenvolvimento de software, como implementar uma arquitetura robusta com uma
documentao simples e eficiente? Na tentativa de responder a essa pergunta, esse artigo ir
apresentar uma forma simples e eficiente para documentar a arquitetura dos seus sistemas.
O que Arquitetura de Software?
A arquitetura de software uma descrio do sistema que auxilia na compreenso de como o
sistema ir se comportar.
Arquitetura um meio de se obter uma anlise antecipada para garantir que a abordagem de
design apresentada, produzir um sistema que alcance os requisitos exigidos pelo cliente, tais
como: desempenho, segurana, disponibilidade, integridade, flexibilidade e etc. Portanto, uma
arquitetura de software consiste na definio de suas camadas, que podem envolver entidades
como: componentes de software, aplicativos externos, sistemas legados e propriedades externas.
Por que devo documentar a arquitetura do sistema?
Segundo Steuart Henderson Britt, "Fazer negcios sem publicidade ou projetar uma arquitetura
sem documentar, como piscar para uma garota no escuro. Voc sabe que est fazendo, mas
ningum mais sabe."
Acho essa frase engraada, porm demonstra a verdadeira necessidade de uma documentao.
Por mais perfeita e adequada que seja sua arquitetura, ser intil para outras pessoas que no a
conhecem e que no podem entend-la bem o suficiente para manuse-la. Portanto, a
documentao se faz essencial para todos os casos.
Na maioria das vezes, a documentao tratada como algo secundrio, algo que as pessoas
fazem porque so obrigadas por um contrato ou gerente que a exige. Estas podem, sim, ser
razes legtimas para se documentar algo, porm, no pode faltar a seriedade e
comprometimento do arquiteto ao desenvolver esse documento, garantindo o valor e serenidade
do mesmo.
Estrutura do documento
Histrico de revises

 Introduo
Viso geral
Requisitos no-funcionais
Mecanismos arquiteturais
Fundamentao
Viso de casos de uso
Componentes
Implantao
Entendendo sua estrutura
Nesta parte do artigo vamos entender, detalhar e ver alguns exemplos para documentar cada fase
apresentada na estrutura do documento.
1. Histrico de revises: alguns dos principais objetivos que essa fase do documento pretende
alcanar so: deixar explcito cada alterao feita no documento; controlar a verso do
documento; deixar explcito o responsvel pela alterao; controlar a veracidade do documento.
Exemplo:

DATA

VERSO

DESCRIO

AUTOR

11/12/2011

1.0

Documento inicial

Flvio Mario

03/01/2012

1.1

Alterao no item 3

Nome do au

2. Introduo: nesta fase do documento, o responsvel deve apresentar de forma clara a

objetividade do trabalho a ser documentado. De forma sucinta, descrever do que se trata o
documento e quais assuntos sero abordados no mesmo.
3. Viso geral: a fase viso geral do documento, tem como objetivo, demonstrar de forma
sucinta, os principais elementos que compe a arquitetura do sistema. Geralmente essa etapa
apresentada com uma figura que deve servir como referncia inicial para qualquer entidade que
tenha ou pretende entender o sistema tecnicamente.
Exemplo:

Figure 1. Imagem que representa a viso geral no documento.

4. Requisitos no-funcionais: nesta fase do documento, necessrio listar os requisitos no
funcionais encontrados no sistema, tais como: portabilidade, usabilidade, desempenho e etc. O
objetivo colocar o nome do requisito e descrever com detalhes suas caractersticas.
Exemplo:

Desempenho

1. A pagina principal tem que ser carregada em no mximo 3

segundos com uma conexo mnima de 256kbps.
2. As pginas que recuperam informaes de sistemas legados,
devem responder em dois segundos a cada 10.000 (contextual) em
uma conexo de 256kbps.
3. As pginas que recuperam informaes de transaes no banco
de dados da prpria aplicao, deve responder em um segundo a
cada 10.000 registros (contextual), retornados em uma conexo de
256kbps.
4. O servidor deve suportar 100.000 conexes simultneas sem
perda de desempenho.

Interoperabilidade

1. Deve ser desenvolvido na plataforma .NET com banco de dados

SQL Server Enterprise ou Oracle 10g.

5. Mecanismos arquiteturais: nesta fase do documento, devemos listar os mecanismos

arquiteturais encontrados no sistema, ou seja, identificar todos os mecanismos de anlise,
mecanismo de design e mecanismo de implementao. O intuito desta etapa verificar e
garantir que todas as preocupaes tcnicas relativas arquitetura do sistema tenham sido
capturadas.
Exemplo:

MECANISMO DE ANLISE

MECANISMO DE DESIGN

MECANISMO DE IMPLEMENTAO

Persistncia

Banco de dados relacional

Integrao com
(Cobrana)

sistemas

SQL Server Enterprise

legados Interface utilizando XML em servio e Web Service e System.IO

arquivo texto.

Log

Implementao dos recursos de log do ADO.NET

componente de persistncia.

Recursos avanados de Web 2.0

Implementao
usabilidade.

Camada de distribuio

Classe de comunicao com o banco, ADO.NET Entity

classe de persistncia.

Front-End

Interface de comunicao com o ASP.NET, Ajax, Silverlight, WPF.

usurio do portal.

Tratamento de excees

Camada para tratar as excees criando ASP.NET e C#.

interaes diferentes para usurios e
tcnicos.

Build

Programao da IDE para validao do Visual Studio Team System Foundation

cdigo fonte.
Server.

Deploy

Configurao da IDE de deploy.

de

recursos

para Silverlight e WPF (Windows Presentation

Foundation).

Visual Studio Team System Foundation

Server.

6. Fundamentao: nesta fase, o arquiteto deve fundamentar todas as decises importantes de

design. Alm disso, deve descrever as alternativas significativas rejeitadas no projeto. Esta
seo pode indicar hipteses, restries, resultados de anlises e experincias significativas para
a arquitetura.
7. Viso de caso de uso: esta fase, ser responsvel por apresentar os casos de uso ou cenrios
escolhidos para a validao da arquitetura apresentada. Casos de uso, backlog, requisitos de
usurios ou qualquer outro nome que represente os itens relevantes para o funcionamento do
sistema final, o intuito exercitar e testar os principais aspectos de risco da arquitetura.

Exemplo:

UC

Motivos da escolha

Caso de uso 1

Descrever o motivo e os itens que sero testados.

Caso de uso 2

...

8. Componentes: nesta fase, o arquiteto deve apresentar o diagrama de componentes.

recomendado como boas praticas de mercado o uso do modelo UML para criao do diagrama,
que deve apresentar os possveis componentes e suas dependncias. Alm disso, o arquiteto
deve criar uma tabela detalhando as responsabilidades de cada componente.
Exemplo:

Figure 2. Representao grfica com diagrama UML para representar os componentes.

Component Descrio
e

BackOffice Descrever de forma sucinta as responsabilidades deste

componente...

Assinante

Servio

Financeiro

Pesquisa

Suporte

Log

Segurana

9. Implantao: nesta fase, o arquiteto deve descreve as configuraes de distribuio dos

componentes de software na rea fsica em que sero implantados.
Exemplo:

Figure 3 Representao de um cenrio para implantao

Concluso
Existem diferentes maneiras e padres para documentao da arquitetura de software, porm,
podemos concluir com esse artigo, que o importante criar um documento que descreve com
clareza os principais aspectos envolvidos no escopo do sistema.
Alm disso, podemos perceber que podemos customizar a documentao de forma que ela se
torne exequvel para realidade de cada projeto. O importante documentar com seriedade e
comprometimento com o seu trabalho.
Dicas
Para aqueles apaixonados pelo assunto, vale a pena dar uma olhada no seguinte portal.
http://www.sei.cmu.edu/architecture/
Referncia

Peter Eeles; Peter Cripps. The Process of Software Architecting, Addison-Wesley

Professional, 2009.
Paul Clements; Felix Bachmann; Len Bass; David Garlan; James Ivers; Reed Little; Paulo
Merson; Robert Nord; Judith Stafford. Documenting Software Architectures: Views and
Beyond, Second Edition, Addison-Wesley Professional, 2010.