184 lines
7.3 KiB
Markdown
184 lines
7.3 KiB
Markdown
# 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 |