docs: initialize engineering starter kit
This commit is contained in:
AzuTear
@@ -0,0 +1,167 @@
|
||||
# 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 |
|
||||
Reference in New Issue
Block a user