--- lib/A3C.pod	2008/06/19 18:24:02	204
+++ lib/A3C.pod	2008/06/19 21:24:26	208
@@ -4,19 +4,60 @@
 
 =head1 DESCRIPTION
 
-This page describes general idea about A3C application and current status of implementation
+This page describes general idea about A3C application and current status of implementation.
+
+Oppinions should be attributed to Dobrica Pavlinusic, and not other developers :-)
+It's surposed to convey a story which is coherent enough for new developer
+to join into project. Most of other documentation is more useful when
+developing and looking into code usage (if it's not documented and tested,
+it doesn't exist) but this part is delivered as pure POD for reading pleasure.
+
+=head1 Models
+
+Models in Jifty are at perl level objects (with validation and
+canonicalization) and tables in database.
+
+For a start, we implement some magic documented in L<A3C::Record> on records
+(rows in database).
+
+Then, we need to mungle data without re-thinking SQL queries which would
+produce same results, so there is L<A3C::SQL> which produce objects that
+look like L<Jifty::Collection>s, but aren't. This allows us to switch into
+SQL in views if needed.
+
+This method is not perfect, and shouldn't be used instead of Jifty models
+just to write SQL because it doesn't do any permission checking. However,
+it's a huge help for compex C<GROUP BY> and C<JOIN> queries which are hard
+to express using L<Jifty::DBI>.
+
+If we needed to generate those queries from within program (from user data,
+for example) something like L<Fey::SQL> would be much better tool.
 
 =head1 LDAP 
 
 Implement LDAP entry and edit interface (insteresting problem since most
-values can have multiple entries which doesn't map nicely to relational
-schema)
+entries can have multiple values which doesn't map nicely to relational
+schema).
+
+=head2 Multiple values
+
+When creating records with ARRAY values C<A3C::Record/create> 
+joins values with magic marker between them to make rest of Jifty happy.
+
+Plan is to use full-text search engine to search over data anyway, so this
+is not serious limitation. If needed, something like bitmap indexes could be
+used at database level to expose thouse values for filtering. For joins we
+would probably need separate materialized many-many tables which could be
+created more-or-less automatically in L<A3C::Record>.
 
 This can in turn be broken down into following tasks:
 
 =head2 Import data from existing LDAP server
 
-C<bin/import-ldap.pl> has embedded documentation
+C<bin/import-ldap.pl> has embedded documentation and uses <A3C::LDAP>
+
+L<http://a3c.skole.hr/ldap/> is user interface to L<A3C::View::LDAP> and
+L<A3C::Action::SyncOrganization>
 
 =head2 Query existing LDAP server
 
@@ -74,12 +115,15 @@
 have to take a look in C<lib/Strix.pm>) implements pure DBI code (ported
 from php) to access data directly. Keep in mind that this data have to be
 cached for any resonable performance. On the other hand, data can be
-structured usefully, for example trees are structured in useful way for JSON
-direct JSON output.
+structured usefully, for example trees are structured in useful way for 
+direct output to JSON.
 
 If tree has C<class> key, it can be set to C<error> so that we can mark
 errors in data using same CSS class in views. This might be useful convention.
 
+I prefer to keep this file documented up to level that make it's usage from Jifty and 
+C<t/50-strix.t> makes sanse, but not more than that.
+
 =head1 HTML
 
 We don't generate HTML using templates. In fact, all HTML is encoded in perl
@@ -91,6 +135,22 @@
 for us anyway) for easier maintenance, probably by same logic as view names
 to skip additional step of mapping when human are watching into code.
 
+In long run, this should allow us to refactor templates at code level and
+create different re-usable widgets which brings us to following topic...
+
+=head1 AJAX
+
+Jifty's way of AJAX are L<Jifty::Manual::PageRegions>.
+
+=head2 Strix navigation
+
+L<http://a3c.skole.hr/strix/navigation>
+
+For now, we have implementation of two-level select which is in sync with
+instance clipboard (implemented by L<A3C::Model::StrixInstanceSelection> and
+L<A3C::View::Strix> and L<A3C::Action::StrixSelectSite>. This is
+good candidate to refactor into reusable widget on it's own.
+
 =head1 BUGS
 
 Many probably, documented in C<TODO> which is also useful for quick overview