first commit

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.