Teammate Voices — Master Architecture

JWT token structure

{
  "sub": "42",
  "email": "[email protected]",
  "role": "MANAGER",
  "iat": 1711000000,
  "exp": 1711000900
}

Token refresh

The Axios interceptor detects 401 responses, calls the refresh endpoint, retries the original request. If refresh also fails, redirect to login.

// In api/client.js — simplified refresh logic
api.interceptors.response.use(null, async (error) => {
  const originalRequest = error.config;
  if (error.response?.status === 401 && !originalRequest._retry) {
    originalRequest._retry = true;
    const { refreshToken } = useAuthStore.getState();
    const { data } = await axios.post('/api/auth/refresh', { refreshToken });
    useAuthStore.getState().setToken(data.accessToken);
    originalRequest.headers.Authorization = `Bearer ${data.accessToken}`;
    return api(originalRequest);
  }
  return Promise.reject(error);
});

Authorization Matrix

Enforced at the Spring Boot service layer, not just the frontend. The frontend hides unauthorized UI elements for UX, but the backend rejects unauthorized API calls regardless.

Error Propagation

Errors flow upward with translation at each boundary:

Oracle                    Spring Boot                  React
─────                    ───────────                  ─────
ORA-00001               → DuplicateResponseException  → "You've already
(unique constraint)       → 409 Conflict                 responded to
                           { code: "DUPLICATE_RESP",     this survey"
                             message: "..." }

ORA-02291               → ResourceNotFoundException   → "Survey not found"
(FK violation)            → 404 Not Found               + redirect to
                           { code: "NOT_FOUND" }         dashboard

Validation failure      → MethodArgumentNotValid      → Field-level
(Bean Validation)         → 400 Bad Request              error messages
                           { code: "VALIDATION_ERROR",   under each input
                             fieldErrors: {...} }

Unhandled exception     → GlobalExceptionHandler      → Generic error
                          → 500 Internal Error           page with
                           { code: "INTERNAL_ERROR" }    retry button

The frontend error handler maps API error codes to user-friendly messages:

const ERROR_MESSAGES = {
  DUPLICATE_RESP:      "You've already responded to this survey.",
  SURVEY_CLOSED:       "This survey is no longer accepting responses.",
  NOT_FOUND:           "The requested resource was not found.",
  VALIDATION_ERROR:    "Please fix the highlighted fields.",
  INTERNAL_ERROR:      "Something went wrong. Please try again.",
};

End-to-End Feature Workflow

When adding a new feature (e.g., "add NPS question type"), follow this sequence:

Step 1: Database

• Add 'NPS' to the chk_q_type CHECK constraint on tv_questions
• Define the NPS question JSON structure in questions_json
• Add any new stored procedure analytics for NPS (promoter/detractor calculation)
• Create a Flyway migration: V{next}__add_nps_question_type.sql

Step 2: Backend

• Add NPS to the QuestionType enum
• Create NPSValidator for NPS-specific validation rules (0-10 range, required follow-up text for detractors)
• Update QuestionService to handle NPS creation and response processing
• Add NPS analytics to pkg_analytics.get_question_breakdown
• Write unit tests for the validator and service

Step 3: Frontend

• Create NPSQuestion component in components/survey/
• Register it in the QUESTION_COMPONENTS map in QuestionRenderer
• Add NPS option to the question type picker in SurveyBuilder
• Create NPSGauge visualization for the analytics dashboard
• Add NPS to the builder's question config panel (0-10 labels, follow-up threshold)

Step 4: Integration test

• End-to-end test: create survey with NPS question → publish → submit response → verify analytics

Testing Strategy

Backend (JUnit 5 + Mockito + Testcontainers)

tests/
├── unit/
│   ├── service/           # Mock repositories, test business logic
│   ├── validator/         # Test validation rules
│   └── mapper/            # Test DTO mapping
├── integration/
│   ├── controller/        # @WebMvcTest with MockMvc
│   ├── repository/        # @DataJpaTest with Testcontainers Oracle
│   └── security/          # Auth flow tests
└── e2e/
    └── SurveyFlowTest.java  # Full create→publish→respond→analytics

Frontend (Vitest + Testing Library + MSW)

tests/
├── components/            # Render tests for UI components
├── hooks/                 # Hook tests with renderHook
├── pages/                 # Page integration tests with MSW mocking
└── e2e/                   # Playwright end-to-end browser tests

Database (utPLSQL)

tests/
├── test_pkg_analytics.sql     # Stored procedure output tests
├── test_triggers.sql          # Audit trigger verification
└── test_constraints.sql       # Constraint enforcement tests

Deployment Pipeline

Environment tiers

CI/CD Flow (GitHub Actions or Jenkins)

Push to main
  │
  ├─ Frontend pipeline
  │   ├─ npm install
  │   ├─ npm run lint
  │   ├─ npm run test
  │   ├─ npm run build (Vite → dist/)
  │   └─ Deploy to CDN / Nginx
  │
  ├─ Backend pipeline
  │   ├─ mvn clean verify (compile + unit tests)
  │   ├─ Integration tests (Testcontainers)
  │   ├─ mvn package (JAR)
  │   ├─ Docker build
  │   └─ Deploy to container orchestrator
  │
  └─ Database pipeline
      ├─ Flyway validate (check pending migrations)
      ├─ Flyway migrate (apply to target env)
      └─ utPLSQL run (stored procedure tests)

Docker Compose (local development)