# 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