taskflow/architect/02-design

TaskFlow Architecture Design

Purpose: Technical architecture and visual representation of TaskFlow system
Audience: Sam (project lead), Frontend/Backend developers, QA team
Scope: System boundaries, component structure, data model, deployment strategy
Last Updated: 2024-09-05
Assumptions: Small team scale (2-15 users), managed cloud deployment, modern browser support

Technical Diagrams

1. System Context Diagram

File: system-context.png
Purpose: Shows TaskFlow's position in the overall ecosystem
Audience: All stakeholders
Key Elements:

• Team members (users) access via HTTPS through browsers
• TaskFlow core application handles task management
• Admin-managed authentication service (no self-registration)
• Clear boundary between internal task management and external user access

Key Assumptions:

• Modern browser requirement (Chrome, Firefox, Safari, Edge)
• HTTPS-only access for security
• Admin controls user account creation and management

2. Container Architecture Diagram

File: container-architecture.png
Purpose: Major technological building blocks and their interactions
Audience: Development team, technical stakeholders
Key Elements:

• Single Page Application (React/Vue) for responsive UI
• REST API backend with business logic and data validation
• Separate databases for task data and user accounts
• JSON API communication between frontend and backend
• SQL-based data persistence

Technology Decisions:

• SPA architecture for responsive desktop/mobile experience
• REST API provides clean separation of concerns
• PostgreSQL for relational data integrity
• Separate user store emphasizes admin-controlled access

3. Data Model Diagram

File: data-model.png
Purpose: Core entities, attributes, and relationships
Audience: Backend developers, database administrators
Key Elements:

• USERS table: Core user identity, admin flag, credentials
• TASKS table: Task data with status/priority enums, foreign key relationships
• Relationships: Users can be assigned tasks and create tasks (many-to-many via foreign keys)

Design Decisions:

• Simple two-table model reflects focused scope (no complex workflows)
• Enum fields for status (Open/In Progress/Blocked) and priority (Low/Medium/High)
• Audit trails via created_at/updated_at timestamps
• Foreign key constraints ensure data integrity

4. Deployment View Diagram

File: deployment-view.png
Purpose: Infrastructure layout and scalability approach
Audience: DevOps, deployment team, infrastructure planning
Key Elements:

• Load balancer (ALB) routes traffic to appropriate tiers
• Web tier serves static assets (React build artifacts)
• Application tier runs REST API servers with auto-scaling
• Data tier uses managed PostgreSQL with automated backups
• Clear separation of stateless (web/app) and stateful (database) components

Platform-Agnostic Decisions:

• Standard 3-tier architecture works on any cloud provider
• Managed services reduce operational overhead
• Auto-scaling groups handle variable load
• Automated backups protect against data loss

3D Isometric Visual

TaskFlow Architecture Overview

File: taskflow-3d-architecture.png
Purpose: Engaging visual representation for stakeholder communication
Audience: Non-technical stakeholders, presentations, documentation
Key Elements:

• Team members with computers showing real usage context
• Load balancer managing traffic distribution
• Multiple React frontend instances for availability
• API server cluster handling business logic
• PostgreSQL database as the foundation

Visual Design Principles:

• Clean isometric perspective shows relationships clearly
• Color coding: Blue (users/frontend), Orange (API/processing), Green (database/storage)
• Flow arrows indicate data movement through the system
• Human figures emphasize the user-centric nature of the system

Architecture Decision Records (ADRs)

ADR-001: Single Page Application Architecture

Context: Need responsive web interface that works on desktop and mobile
Decision: Build React/Vue SPA with responsive design
Consequences:

• ✅ Single codebase for all screen sizes
• ✅ Modern, fast user experience
• ❌ Requires JavaScript enabled
• ❌ Initial bundle size consideration

Alternatives Rejected:

• Server-rendered pages (slower interactions)
• Separate mobile app (out of scope)

ADR-002: REST API Backend

Context: Need clean separation between UI and business logic
Decision: JSON REST API with clear CRUD operations
Consequences:

• ✅ Platform-agnostic API design
• ✅ Easy testing and development
• ✅ Future integration possibilities
• ❌ Multiple round trips for complex operations

Alternatives Rejected:

• GraphQL (overkill for simple CRUD)
• Server-side rendering (couples UI and API)

ADR-003: PostgreSQL for Data Persistence

Context: Need reliable data storage with referential integrity
Decision: PostgreSQL as primary database
Consequences:

• ✅ ACID transactions prevent data loss
• ✅ Foreign key constraints ensure consistency
• ✅ Mature ecosystem and tooling
• ❌ Requires database administration knowledge

Alternatives Rejected:

• NoSQL (unnecessary for relational data)
• SQLite (insufficient for multi-user access)

ADR-004: Admin-Controlled User Management

Context: Security requirement, no self-registration
Decision: All user accounts created by administrators
Consequences:

• ✅ Controlled access and security
• ✅ Simplified onboarding process
• ❌ Administrative overhead for user creation
• ❌ Cannot scale to public access

Alternatives Rejected:

• Self-registration (security risk)
• External SSO (adds complexity)

Risk Assessment

Technical Risks

• Medium: Single database could become bottleneck (mitigation: read replicas)
• Low: Browser compatibility issues (mitigation: modern browser requirement)
• Low: API rate limiting needs (mitigation: reasonable user scale assumption)

Security Risks

• High: Password storage security (mitigation: bcrypt hashing, never plain text)
• Medium: Session management (mitigation: secure tokens, HTTPS only)
• Low: SQL injection (mitigation: parameterized queries, ORM usage)

Operational Risks

• Medium: Database backup and recovery (mitigation: automated backups, tested restore procedures)
• Low: Application server failures (mitigation: auto-scaling, health checks)

Quality Attribute Scenarios

Performance

• Scenario: User creates task and assigns to team member
• Response: Task appears in assignee's list within 2 seconds
• Measure: 95th percentile response time ≤ 2000ms

Availability

• Scenario: Primary API server fails during business hours
• Response: Load balancer routes to healthy server automatically
• Measure: Service continues with <30 second disruption

Security

• Scenario: User attempts to access tasks not assigned to them
• Response: System denies access and logs attempt
• Measure: Zero unauthorized data access incidents

Usability

• Scenario: New user completes task creation workflow
• Response: Task created successfully in ≤3 steps
• Measure: 90% of test users complete without assistance