Master architecture skill for the Teammate Voices survey application. Ties together all tier-specific skills and covers cross-cutting concerns: authentication flow, authorization matrix, error handling strategy, logging, deployment pipeline, environment configuration, testing strategy, API versioning, CORS, monitoring, and the end-to-end workflow for building a new feature across all three tiers. Use this skill whenever the user asks about the overall system, cross-cutting concerns like auth or deployment, how the tiers connect, end-to-end feature implementation, testing strategy, CI/CD pipeline, environment setup, or any question that spans multiple tiers. Also trigger when the user mentions 'how does auth work', 'deployment', 'testing', 'CI/CD', 'environments', 'monitoring', 'logging', 'end to end', 'full stack', or asks how to add a new feature to Teammate Voices.
This skill is the connective tissue between the tier-specific skills. It covers everything that spans multiple layers — authentication flowing from frontend to backend to database, error propagation from Oracle through Spring Boot to React, the deployment pipeline that builds and ships all three tiers, and the step-by-step workflow for implementing a new feature end-to-end.
teammate-voices-design-system — UI tokens, components, Apple-inspired guidelinestv-frontend — React architecture, routing, state managementtv-backend — Spring Boot controllers, services, repositoriestv-database — Oracle schema, JSON columns, stored procedurestv-components — Survey renderer, analytics dashboard, admin panelReact LoginPage Spring Boot AuthController Oracle TV_USERS
│ │ │
│ POST /api/auth/login │ │
│ { email, password } │ │
│ ──────────────────────────>│ │
│ │ SELECT by email │
│ │ ──────────────────────────>│
│ │ user row │
│ │ <──────────────────────────│
│ │ │
│ │ Verify BCrypt hash │
│ │ Generate JWT (access 15m) │
│ │ Generate refresh (7d) │
│ │ Update last_login_at │
│ │ ──────────────────────────>│
│ │ │
│ { accessToken, │ │
│ refreshToken, │ │
│ user: { id, name, │ │
│ email, role } } │ │
│ <──────────────────────────│ │
│ │ │
│ Store tokens in Zustand │ │
│ Redirect to /dashboard │ │
{
"sub": "42",
"email": "[email protected]",
"role": "MANAGER",
"iat": 1711000000,
"exp": 1711000900
}
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);
});
| Resource | ADMIN | MANAGER | RESPONDENT |
|---|---|---|---|
| Create survey | Yes | Yes | No |
| Edit own survey | Yes | Yes | No |
| Edit any survey | Yes | No | No |
| Publish survey | Yes | Yes | No |
| Delete survey | Yes | Own only | No |
| View analytics | Yes | Own surveys | No |
| Take survey | Yes | Yes | Yes |
| Manage users | Yes | No | No |
| View admin panel | Yes | No | No |
| Export data | Yes | Own surveys | No |
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.
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.",
};
When adding a new feature (e.g., "add NPS question type"), follow this sequence:
'NPS' to the chk_q_type CHECK constraint on tv_questionsquestions_jsonV{next}__add_nps_question_type.sqlQuestionType enumNPSValidator for NPS-specific validation rules (0-10 range, required follow-up text for detractors)QuestionService to handle NPS creation and response processingpkg_analytics.get_question_breakdownNPSQuestion component in components/survey/QUESTION_COMPONENTS map in QuestionRendererSurveyBuilderNPSGauge visualization for the analytics dashboardtests/
├── 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
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
tests/
├── test_pkg_analytics.sql # Stored procedure output tests
├── test_triggers.sql # Audit trigger verification
└── test_constraints.sql # Constraint enforcement tests
| Environment | Purpose | Database | URL |
|---|---|---|---|
| Local | Development | Oracle XE Docker | localhost:3000 / :8080 |
| Dev | Integration testing | Oracle Dev instance | dev.tv.internal |
| Staging | Pre-production QA | Oracle Staging (prod clone) | staging.tv.internal |
| Production | Live | Oracle Production (RAC) | teammatevoices.company.com |
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)