diff --git a/architect/02-design/.gitkeep b/architect/02-design/.gitkeep new file mode 100644 index 0000000..1b1c0b4 --- /dev/null +++ b/architect/02-design/.gitkeep @@ -0,0 +1,3 @@ +# Design Directory + +Technical architecture diagrams and 3D visuals. \ No newline at end of file diff --git a/architect/02-design/README.md b/architect/02-design/README.md new file mode 100644 index 0000000..6c972cc --- /dev/null +++ b/architect/02-design/README.md @@ -0,0 +1,184 @@ +# 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 \ No newline at end of file diff --git a/architect/02-design/container-architecture.png b/architect/02-design/container-architecture.png new file mode 100644 index 0000000..0ed3c8e Binary files /dev/null and b/architect/02-design/container-architecture.png differ diff --git a/architect/02-design/data-model.png b/architect/02-design/data-model.png new file mode 100644 index 0000000..fa2d7f0 Binary files /dev/null and b/architect/02-design/data-model.png differ diff --git a/architect/02-design/deployment-view.png b/architect/02-design/deployment-view.png new file mode 100644 index 0000000..0ec7029 Binary files /dev/null and b/architect/02-design/deployment-view.png differ diff --git a/architect/02-design/system-context.png b/architect/02-design/system-context.png new file mode 100644 index 0000000..10eded9 Binary files /dev/null and b/architect/02-design/system-context.png differ diff --git a/architect/02-design/taskflow-3d-architecture.png b/architect/02-design/taskflow-3d-architecture.png new file mode 100644 index 0000000..d0d83de Binary files /dev/null and b/architect/02-design/taskflow-3d-architecture.png differ