# Atlas Desk

Atlas Desk is a fictional internal support workflow system for small operations
teams.

## Vision

Give support teams one reliable place to triage customer requests, assign work,
track status, and understand operational bottlenecks without relying on shared
mailboxes or spreadsheets.

## Goals

- Reduce average request triage time by 40 percent.
- Make ownership and status visible for every support request.
- Provide an audit trail for customer-impacting decisions.

## Non-Goals

- Replace the billing system.
- Provide public customer self-service in the first release.
- Support multi-region deployment before usage requires it.

## Functional Requirements

| ID | Requirement | Priority | Status |
| --- | --- | --- | --- |
| FR-001 | Agents can create, assign, and close support requests. | Must | Accepted |
| FR-002 | Managers can view queue health and overdue work. | Must | Accepted |
| FR-003 | Users can add internal notes to requests. | Should | Proposed |
| FR-004 | The system sends notifications when ownership changes. | Should | Proposed |

## Non-Functional Requirements

| Category | Requirement | Measurement |
| --- | --- | --- |
| Availability | Available during support hours. | 99.5 percent monthly uptime. |
| Performance | Common list and detail views feel immediate. | P95 API latency below 300 ms for core endpoints. |
| Security | Only authorized users can view or mutate requests. | Authorization tests cover each role. |
| Privacy | Customer contact data is minimized and auditable. | Sensitive fields are excluded from debug logs. |
| Maintainability | New queue workflows can be added without rewriting the core model. | Feature modules own their workflows. |

## Users And Roles

| Role | Description | Key Permissions |
| --- | --- | --- |
| Agent | Handles support requests. | Create, update, assign, comment, close. |
| Manager | Oversees queue health. | All agent permissions plus reporting and reassignment. |
| Auditor | Reviews historical activity. | Read-only access to requests and audit events. |

## Tech Stack

| Area | Choice | Notes |
| --- | --- | --- |
| Language | C# and TypeScript | Backend and frontend use separate type systems. |
| Framework | ASP.NET Core and Vue | Conventional web application stack. |
| Frontend | Vue 3 | Single-page application. |
| Backend | ASP.NET Core | Modular monolith API. |
| Database | PostgreSQL | Primary transactional store. |
| Messaging | None initially | Reconsider if notification volume grows. |
| Search | PostgreSQL full-text search | Sufficient for initial request search. |
| Cache | None initially | Add only after measured pressure. |

## Runtime

| Environment | Purpose | URL or Entry Point | Notes |
| --- | --- | --- | --- |
| Local | Development | `https://localhost:5173` | Frontend talks to local API. |
| Test | Automated validation | CI service containers | Uses ephemeral PostgreSQL. |
| Staging | Release verification | `https://staging.atlas-desk.example` | Mirrors production config. |
| Production | Live system | `https://atlas-desk.example` | Single-region deployment. |

## Infrastructure

| Component | Provider | Responsibility | Notes |
| --- | --- | --- | --- |
| Hosting | Managed container platform | Run API and frontend assets. | One service initially. |
| Storage | PostgreSQL managed database | Store requests, users, audit events. | Daily backups. |
| Network | Managed load balancer | TLS and routing. | Internal admin access restricted. |

## Database

| Field | Value |
| --- | --- |
| Database engine | PostgreSQL |
| Migration tool | Entity Framework Core migrations |
| Backup strategy | Daily automated backup with 14-day retention |
| Restore strategy | Restore to staging monthly as a drill |
| Data retention | Closed requests retained for 3 years |

## CI/CD

| Pipeline | Trigger | Required Checks | Notes |
| --- | --- | --- | --- |
| CI | Pull request and push to main | Build, unit tests, integration tests, lint | Blocks merge. |
| Deploy staging | Push to main | CI success | Automatic. |
| Deploy production | Manual approval | Staging smoke test | Release owner approves. |

## Deployment

| Area | Policy |
| --- | --- |
| Deployment strategy | Rolling container deployment |
| Rollback strategy | Redeploy previous image and disable feature flags |
| Release owner | Support platform maintainer |
| Change window | Weekdays before 15:00 local support time |

## Authentication

| Field | Value |
| --- | --- |
| Authentication method | OpenID Connect |
| Identity provider | Company identity provider |
| Session model | Secure HTTP-only cookie |
| Token lifetime | 8-hour workday session |

## Authorization

| Field | Value |
| --- | --- |
| Authorization model | Role-based access with policy checks |
| Role source | Identity provider group claims synchronized at login |
| Policy location | Backend authorization policies |
| Audit requirements | Assignment and close actions generate audit events |

## Logging

| Field | Value |
| --- | --- |
| Logging library | Structured backend logging |
| Log sink | Central log service |
| Correlation ID | Created at API edge and returned in responses |
| Sensitive data policy | Do not log customer email bodies or tokens |

## Monitoring

| Signal | Tool | Alert Policy |
| --- | --- | --- |
| Availability | Health checks | Alert after 3 failed checks. |
| Errors | Error tracking | Alert on elevated 5xx rate. |
| Performance | API metrics | Alert when P95 exceeds 500 ms for 15 minutes. |
| Business metrics | Queue dashboard | Alert managers when overdue work exceeds threshold. |

## Testing

| Test Type | Tooling | Required When |
| --- | --- | --- |
| Unit | Backend and frontend test runners | Domain rules, view logic, formatters. |
| Integration | API tests with PostgreSQL | Persistence, auth, and queue workflows. |
| End-to-end | Browser automation | Critical request lifecycle. |
| Performance | Scripted API checks | Before major queue or reporting changes. |
| Security | Dependency audit and auth tests | Each release candidate. |

## Roadmap

| Milestone | Target | Outcome |
| --- | --- | --- |
| M1 | Q1 | Request intake, assignment, and closure. |
| M2 | Q2 | Reporting dashboard and overdue alerts. |
| M3 | Q3 | Customer-visible request status page. |

## Open Questions

| Question | Owner | Needed By | Status |
| --- | --- | --- | --- |
| Should notification delivery use email only or chat integration too? | Product | M2 planning | Open |
| Is audit export required for compliance reviews? | Operations | M1 release | Open |