first commit

docs/api.md

@@ -0,0 +1,19 @@
+# API Notes
+
+Base path: `/api/v1`.
+
+Current scaffold routes:
+
+- `GET /healthz`
+- `GET /readyz`
+- `POST /api/v1/auth/login`
+- `POST /api/v1/auth/logout`
+- `POST /api/v1/auth/refresh`
+- `GET /api/v1/users`
+- `POST /api/v1/users/invitations`
+- `GET /api/v1/clients`
+- `POST /api/v1/clients`
+- `GET /api/v1/clients/:clientId`
+- `PATCH /api/v1/clients/:clientId`
+- `GET /api/v1/calendar/week`
+- `GET /api/v1/calendar/holidays?year=2026`

docs/architecture.md

@@ -0,0 +1,36 @@
+# Architecture Notes
+
+## Initial Decisions
+
+- PostgreSQL is the system of record.
+- BrasilAPI is the initial provider for Brazilian national holidays.
+- Calendar data from external providers must be cached or persisted before production use.
+- Regional holidays and custom commemorative dates are first-party data managed inside the app.
+- Client users are read-only in the MVP.
+- Agency users can only access assigned clients unless they are super admins.
+
+## Backend Boundaries
+
+- `auth`: login, session/token handling, password hashing, invitation acceptance.
+- `users`: user management and invitations.
+- `clients`: client records and user-client access.
+- `calendar`: provider integrations, holiday sync, weekly dashboard, calendar views.
+- `security`: headers, CORS, rate limiting, auth middleware.
+- `database`: migrations, connection handling, transactions.
+
+## Frontend Boundaries
+
+- Authenticated app shell.
+- Weekly dashboard.
+- Client list.
+- Client calendar.
+- Day detail.
+- User and invitation management.
+- Custom dates.
+
+## Data Rules
+
+- Calendar-only dates should be stored as `date`.
+- Instants with time should be stored in UTC.
+- The operational timezone is `America/Sao_Paulo`.
+- Audit logs should record administrative and content changes.

docs/security.md

@@ -0,0 +1,26 @@
+# Security Notes
+
+The application must follow OWASP guidance throughout implementation.
+
+## Required Controls
+
+- Strong password hashing.
+- Login rate limiting.
+- Backend role and client-scope authorization.
+- Restrictive CORS.
+- HTTP security headers.
+- Parameterized database queries.
+- Safe upload handling.
+- Protected attachment access.
+- Invitation tokens with expiration and single use.
+- Audit logs for sensitive changes.
+- No secrets in the repository.
+
+## Upload Rules
+
+- Limit file size.
+- Restrict MIME types.
+- Validate actual file content.
+- Rename files before storage.
+- Do not execute or directly expose uploaded files.
+- Check client access before serving files.